TMS320C3x 
C Source Debugger 
User’s Guide 


SPRU053 
November 1993 


sag TEXAS 


INSTRUMENTS 


Printed on Recycled Paper 


TMS320C3x C Source Debugger User’s Guide 
Reader Response Card 


Texas Instruments wants to provide you with the best documentation possible—please help us by answering these 
questions and returning this card. 


How have you used this manual? 
L To look up specific information or procedures when needed (as a reference). 
C1 Toread chapters about subjects of specific interest. 


L] Toread from front to back before using the product. 


Did you use the Tutorial (Chapter 2)? 
LI Yes LI No 


Which additional subjects should be included in future versions of the Tutorial? 


Please describe any mistakes or misleading information that you found (include page numbers). 


Which topics should this document describe in greater detail? 


Please list information that was difficult to find and why (not in index, not in a logical location, etc.). 


Please provide any specific suggestions that you have for improving the content of this document. 


Are there specific, useful features of this user’s guide that should be retained in future versions of this document? 


Additional comments: 


Thank you for taking the time to fill out this card. 


Name Title 

Company 

Address 

City State Zip/Country 


May we call you to discuss your comments? If so, please include phone number 


November 1993 


bala TEXAS 
INSTRUMENTS 


mu toKys0l exch a OmclolU | cor-m BY-) olblele(-le 
Reference Card 


Phone Number 
DSP Hotline: (713) 274-2320 


Invoking the Debugger 

Emulator: emu3x [filename] [-options] 
EVM: evm30 [filename] [-options] 
Simulator: sim3x [filename] [-options] 
Debugger Options 

Option Description 

—b[b] Select the screen size. 


Option _ Characters. 
none 80 X 25 (default) 


—b 80 x 43 (EGA or VGA) 
—bb 80 x 50 (VGA only) 
-i pathname Identify additional directories. Identifies 
directories that contain source files. 
—mm0 Select the mode. (simulator only) Tells de- 
—mm1 bugger to operate in microprocessor (0) or 
microcomputer (1) mode (0 is the default). 
—mv30 Select the device version. (simulator 
—mv31 only) Identifies ‘C30 or ’C31 memory map 


(‘C30 is the default). 


-—p portaddress Identify the port address. (emulator and 
EVM) Identifies the I/O port address that the 
debugger uses for communicating with the 
device. 


—profile Enter the profiling environment. (emula- 
tor and simulator) Brings up the debugger 
in a profiling environment. 


-s Load symbol table only. Tells the debug- 
ger to load filename’s symbol table only. 


—t filename Identify new initialization file. Allows 
you to specify an initialization file. 


Vv Load without symbol table. Loads only 
global symbols; later, local symbols are 
loaded as needed. Affects all loads. 


—x Ignore D_OPTIONS. Ignores options sup- 
plied with DLOPTIONS. 


Summary of Debugger Commands 


? expression [, display format| 


addr address 
addr function name 


alias [alias name [, command string’) ] 
asm 

ba address 

bd address 

bl 

border [active] [, [ inactive] [,resize] ] 
br 

c 

calls 


cd [directory name] 
chdir [directory name] 


cls 

cnext [expression] 

color area, attr, [,attro [,attr3 [,attrg]]] 
cstep [expression] 


dasm address 
dasm function name 


dir [directory] 

disp expression [, display format| 
dlog filename [, {fa|w}] 

echo string 

else 

endif 

endloop 


eval expression 
e expression 


file filename 
fill address, length, data 


func function name 
func address 


go [address] 
halt 


if Boolean expression 
debugger command list 
[else 

debugger command list] 
endif 


load object filename 


loop expression 
debugger command list 
endloop 


ma address, length, type 
map {on | off} 


mc port adoress, filename, {READ | WRITE} 


p = profiler only d = basic debugger only 
b = both profiler and basic debugger simulator only 


Qe 
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Summary of Debugger Commands 


md address 

mem expression [, display format| 
mi port address, {READ|WRITE} 
mix 

ml 

move [X, Y [, width, length ] ] 

mr 

ms address, length, filename 
next [expression] 

patch address, assembly language instruction 
pf starting point |, update rate] 
pine pinname filename 

pind pinname 

pinl 

pq starting point |, update rate] 

pr [clear data [, update rate] | 
prompt new prompt 

quit 

reload object filename 

reset 


restart 
rest 


return 
ret 


run [expression] 

runb 

runf 

sa address 

scolor area, attr, [, attro [, attr3 [, attrg]]] 
sconfig [filename] 

sd address 

setf [data type, display format ] 

size [wiath, length ] 

sl 

sload object filename 

sound on | off 

sr 

ssave [filename] 

step [expression] 

system [operating-system command [, flag ] | 
take batch filename [, suppress echo flag] 
unalias alias name 

use directory name 

vaa filename 

vac filename 


p = profiler only d = basic debugger only 
b = both profiler and basic debugger simulator only 
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Summary of Debugger Commands 


version b 
vr p 
wa expression [,[ label], display format | d 
wd index number d 
whatis symbol! d 
win WINDOW NAME b 
wr d 
zoom b 
p= profiler only d = basic debugger only 
b = both profiler and basic debugger T simulator only 

Border Styles 

(BORDER Command) 
Index Style 
0 Double-lined box 
1 Single-lined box 
2 Solid 1/2-tone top, double-lined sides/bottom 
3 Solid 1/4-tone top, double-lined sides/bottom 
4 Solid box, thin border 
5 Solid box, heavy sides, thin top/bottom 
6 Solid box, heavy borders 
7 Solid 1/2-tone box 
8 Solid 1/4-tone box 

Colors and Atiributes 

(COLOR/SCOLOR Commands) 
black blue green cyan 
red magenta yellow white 
bright blink 

Area Names 

(COLOR/SCOLOR Commands) 
menu_bar menu_border menu_entry menu_cmd 
menu_hilite menu_hicmd  win_border win_hiborder 
win_resize field_text field_hilite field_edit 
field_label field_error cmd_prompt  cmd_input 
cmd_cursor cmd_echo asm_data asm_cdata 
asm_label asm_clabel background _ blanks 
error_msg file_line file_eof file_text 
file_brk file_pc file_pc_brk 


Memory Types 


To identify this kind of Use this keyword as the 
memory type parameter 
read-only memory R, ROM, or READONLY 
write-only memory W, WOM, or WRITEONLY 
read/write memory R|W or RAM 
no-access memory PROTECT 
input port IPORT or IN PORT 
output port OPORT or OUT PORT 
input/output port IOPORT 

Display Formats 


(?, DISP, MEM, SETF, and WA Commands) 


Para- Result 
meter 


Para- Result 
meter 

* Default for the data type oO Octal 
ASCII character (bytes) p Valid address 
d Decimal s  ASCllstring T 


e Exponential floating 
point 


u Unsigned decimal 


x Hexadecimal 


f Decimal floating point 


t ?, DISP, SETF, and WA commands only 


Switching Modes 
Use this 
To do this function key 
Switch debugging modes in this order: 
(~ auto ——-» assembly mas 
Running Code 
Use these 
To do this function keys 
Run code from the current PC 
Single-step from the current PC 


Single-step code from the current PC; step 
over function calls 


Selecting or Closing a Window 


Use these 
To do this function keys 
Select the active window 
Close the CALLS or DISP window 
Editing Text on the Command Line 
Use these 
To do this function keys 
Enter the current command 
Move back over text without erasing char- 
acters or 


Move forward through text without erasing CTRL 
characters 


Move back over text while erasing charac- DELETE 
ters 


characters 


Move forward through text while erasing 


Insert text into the characters that are al- INSERT 
ready on the command line 


Using the Command History 


Use these 
To do this function keys 


Repeat the last command that you entered 


Move backward, one command at a time, TAB 
through the command history 


Move forward, one command at a time, 


through the command history 


Editing Data or Selecting the Active Field 


Use this 
To do this function key 


Oh FILE or DISASSEMBLY window: Set 
or clear a breakpoint 


(1 CALLS window: Display the source to 
a listed function 


O Any data-display window: Edit the con- 
tents of the current field 


O DISP window: Open an additional 
DISP window 


Halting or Escaping From an Action 


Use this 
To do this function key 
QO) Halt program execution ESC 
QO Close a pulldown menu 
L} Undo an edit of the active field in a 
data-display window 
Halt the display of a long list of data 
Displaying Pulldown Menus 
Use these 
To do this function keys 
Display the Load menu ALT 
Display the Break menu 
Display the Watch menu ALT 
Display the Memory menu (m] 
Display the Color menu ALT 
Display the MoDe menu at} (0] 
Display the Pin menu ALT (P) 
Display an adjacent menu or 
Execute any of the choices from a Press the high- 
displayed pulldown menu lighted letter cor 
sponding to you 
choice 


Moving or Sizing a Window 


Enter the MOVE or SIZE command without parameters, then use 
the arrow keys: 


Use these 
To do this function keys 
[1 Move the window down one line GW) 
(1) Make the window one line longer 
L} Move the window up one line (4) 
CL) Make the window one line shorter 
1) Move the window left one character (=) 
position 
CL) Make the window one character nar- 
rower 
L} Move the window right one character 
position 
Make the window one character wid- 


er 


Scrolling the Active Window’s Contents 


To do this 


Scroll up through the window contents, one 
window length at a time 


Scroll down through the window contents, 
one window length at a time 


Move the field cursor up one line at a time 
Move the field cursor down one line at atime 


[1 FILE window only: Scroll left 8 char- 
acters at a time 


1) Other windows: Move the field cur- 
sor left 1 field; at the first field on a 
line, wrap back to the last fully dis- 
played field on the previous line 


1 FlLEwindowonly: Scroll right 8 char- 
acters at a time 


C) Other windows: Move the field cur- 
sor right 1 field; at the last field ona 
line, wrap around to the first field on 
the next line 


FILE window only: Adjust the window’s con- 
tents so that the first line of the text file is at 
the top of the window 


FILE window only: Adjust the window’s con- 
tents so that the last line of the text file is at 
the bottom of the window 


DISP windows only: Scroll up through an 
array of structures 


DISP windows only: Scroll down through an 
array of structures 


Use these 
function keys 


PAGE 
UP 


PAGE 
DOWN 


WIS|S) By) & 


[4 


CTRL 


PAGE 
UP 


lohy) 
o> 
Q) 
i 


CTRL 
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Profiler Reference Card Entering the Profiling Environment 


The profiling evironment is supported under all platforms except 


DOS. 

Basic Profiling Commands os 
Emulator: emu3x —profile 
EVM: evm30 -profile 
Running a Profiling Session Simulator: sim3x —profile 


Command 


Description 


pf starting point|, update rate] Runa full profiling 
session 


pq starting point [, update rate] Run a quick profil- Debugger Commands That Can Be Used in the 


ing session Profiling Environment 
pr [clear data [, update rate]] Resume a profilng 
session that has 
halted ? LOAD MR SLOAD 
pr [clear data [, update rate]] Resume a profilng ALIAS MA PROMPT SYSTEM 
session that has CD MAP QUIT TAKE 
halted 
CLS MC RELOAD UNALIAS 
DASM MD RESET USE 
Defining Stopping Points DIR MI RESTART VERSION 
Command Description EVAL ML SCONFIG WIN 
sa address Add a stopping FILE MOVE SIZE ZOOM 
polnt FUNC 
sd address Delete a stopping 
point 
= ear te oop: Debugger Commands That Can’t Be Used in the 
pine Profiling Environment 
sl View a list of all 
current stopping 
points ADDR CNEXT MS RUNF 
ASM COLOR NEXT SCOLOR 
BA CSTEP PINC SSAVE 
Saving Profile Data to a File 
BD DISP PIND STEP 
Command Description BL FILL PINL WA 
vac filename Save the contents 
of the PROFILE BORDER GO RETURN WD 
window to a sys- BR HALT RUN WHATIS 
tem file 
Cc MEM RUNB WR 


Save all data for 
the current view CALLS MIX 


vaa filename 


Marking Areas 


To mark this area C only Disassembly only 


Lines 


D By line number, address 
QD All lines in a function 


MALE address 
MALEF function 


MCLE filename, line number 
MCLF function 


Ranges 


@ By line numbers MCRE filename, line number, line number | MARE address, address 


Functions 


Q By function name MCFE function not applicable 


Q All functions in a module 
D All functions everyhwhere 


Disabling Marked Areas 


To disable this area 
Lines 

Q By line number, address 
Q All lines in a function 

D All lines in a module 

Q All lines everywhere 


Ranges 

@ By line numbers, addresses 
Q All ranges in a function 

D All ranges in a module 

D All ranges everywhere 


Functions 

Q By function name 

Q All functions in a module 
Q All functions everyhwhere 


All areas 

D All areas in a function 
Q All areas in a module 

Q All areas everyhwhere 


MCFM filename 
MCFG 


C only 


DCLE filename, line number 
DCLF function 

DCLM filename 

DCLG 


DCRE filename, line number 
DCRF function 

DCRM filename 

DCRG 


DCFE function 
DCFM filename 
DCFG 


DCAF function 
DCAM filename 
DCAG 


Disassembly only 


DALE address 

DALF function 

DALM filename 
DALG 


DARE address 

DARF function 

DARM filename 
DARG 


not applicable 


DAAF function 
DAAM filename 
DAAG 


C and Disassembly 


not applicable 
DBLF function 
DBLM filename 
DBLG 


not applicable 
DBRF function 
DBRM filename 
DBRG 


not applicable 
DBFM filename 
DBFG 


DBAF function 
DBAM filename 
DBAG 


Enabling Disabled Areas 


To disable this area 
Lines 

@ By line number, address 
Q All lines in a function 

D All lines in a module 

D All lines everywhere 


Ranges 

@ By line numbers, addresses 
Q All ranges in a function 

D All ranges in a module 

D All ranges everywhere 


Functions 

Q By function name 

Q All functions in a module 
Q All functions everyhwhere 


All areas 

Q All areas in a function 
Q All areas in a module 

Q All areas everyhwhere 


Unmarking Areas 


To disable this area 
Lines 

Q By line number, address 
Q All lines in a function 

D All lines in a module 

D All lines everywhere 


Ranges 

@ By line numbers, addresses 
Q All ranges in a function 

Q All ranges in a module 

QD All ranges everywhere 


Functions 

Q By function name 

Q All functions in a module 
Q All functions everyhwhere 


All areas 

Q All areas in a function 
Q All areas in a module 

Q All areas everyhwhere 


C only 


ECLE filename, line number 
ECLF function 

ECLM filename 

ECLG 


ECRE filename, line number 
ECRF function 

ECRM filename 

ECRG 


ECFE function 
ECFM filename 
ECFG 


ECAF function 
ECAM filename 
ECAG 


C only 


UCLE filename, line number 
UCLF function 

UCLM filename 

UCLG 


UCRE filename, line number 
UCRF function 

UCRM filename 

UCRG 


UCFE function 
UCFM filename 
UCFG 


UCAF function 
UCAM filename 
UCAG 


Disassembly only 


EALE address 

EALF function 

EALM filename 
EALG 


EARE address 

EARF function 

EARM filename 
EARG 


not applicable 


EAAF function 
EAAM filename 
EAAG 


Disassembly only 


UALE address 

UALF function 

UALM filename 
UALG 


UARE address 

UARF function 

UARM filename 
UARG 


not applicable 


UAAF function 
UAAM filename 
UAAG 


C and Disassembly 


not applicable 
EBLF function 
EBLM filename 
EBLG 


not applicable 
EBRF function 
EBRM filename 
EBRG 


not applicable 
EBFM filename 
EBFG 


EBAF function 
EBAM filename 
EBAG 


C and Disassembly 


not applicable 
UBLF function 
UBLM filename 
UBLG 


not applicable 
UBRF function 
UBRM filename 
UBRG 


not applicable 
UBFM filename 
UBFG 


UBAF function 
UBAM filename 
UBAG 


Changing the PROFILE Window Display 


Viewing specific areas 


To disable this area 
Lines 

@ By line number, address 
Q All lines in a function 

Q All lines in a module 

Q All lines everywhere 


Ranges 

@ By line numbers, addresses 
Q All ranges in a function 

D All ranges in a module 

D All ranges everywhere 


Functions 

Q By function name 

Q All functions in a module 
Q All functions everyhwhere 


All areas 

D All areas in a function 
Q All areas in a module 

Q All areas everyhwhere 


C only 


Disassembly only 


VFCLE filename, line number VFALE address 


VFCLF function 
VFCLM filename 
VFCLG 


VFCRE filename, line number 
VFCRF function 

VFCRM filename 

VFCRG 


VFCFE function 
VFCFM filename 
VFCFG 


VFCAF function 
VFCAM filename 


VFALF function 
VFALM filename 
VFALG 


VFARE address 

VFARF function 

VFARM filename 
VFARG 


not applicable 


VFAAF function 
VFAAM filename 
VFAAG 


Sorting the data 


VFCAG 
Viewing different data 
To view this information Use this 

command 

Count vDC 
Inclusive VDI 
Inclusive, maximum VDN 
Exclusive VDE 
Exclusive, maximum VDX 
Address VDA 
All VDL 


To sort on this data 


Count 

Inclusive 

Inclusive, maximum 
Exclusive 

Exclusive, maximum 
Address 

Data 


C and Disassembly 


not applicable 
VFBLF function 
VFBLM filename 
VFBLG 


not applicable 
VFBRF function 
VFBRM filename 
VFBRG 


not applicable 
VFBFM filename 
VFBFG 


VFBAF function 
VFBAM filename 
VFBAG 


Use this 
command 


VvSC 
VSI 

VSN 
VSE 
VSX 
VSA 
VSD 


IMPORTANT NOTICE 


Texas Instruments Incorporated (TI) reserves the right to make changes to its products or to 
discontinue any semiconductor product or service without notice, and advises its customers to 
obtain the latest version of relevant information to verify, before placing orders, that the 
information being relied on is current. 


Tl warrants performance of its semiconductor products and related software to current 
specifications in accordance with Tl’s standard warranty. Testing and other quality control 
techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing 
of all parameters of each device is not necessarily performed, except those mandated by 
government requirements. 


Please be aware that TI products are not intended for use in life-support appliances, devices, 
or systems. Use of TI product in such applications requires the written approval of the 
appropriate TI officer. Certain applications using semiconductor devices may involve potential 
risks of personal injury, property damage, or loss of life. In order to minimize these risks, 
adequate design and operating safeguards should be provided by the customer to minimize 
inherent or procedural hazards. Inclusion of TI products in such applications is understood to be 
fully at the risk of the customer using TI devices or systems. 


Tl assumes no liability for applications assistance, customer product design, software 
performance, or infringement of patents or services described herein. Nor does TI warrant or 
represent that any license, either express or implied, is granted under any patent right, copyright, 
mask work right, or other intellectual property right of Tl covering or relating to any combination, 
machine, or process in which such semiconductor products or services might be or are used. 


WARNING 


This equipment is intended for use in a laboratory test environment only. It generates, uses, and 
can radiate radio frequency energy and has not been tested for compliance with the limits of 
computing devices pursuant to subpart J of part 15 of FCC rules, which are designed to provide 
reasonable protection against radio frequency interference. Operation of this equipment in other 
environments may cause interference with radio communications, in which case the user at his 
own expense will be required to take whatever measures may be required to correct this 
interference. 
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Preface 


Read This First 


What Is This Book About? 


This book tells you how to use the TMS320C3x C source debugger with these 
debugging tools: 


__J Emulator 
[J] Evaluation module (EVM) 
[__] Simulator 


All three tools support code development for both the TMS320C30 and the 
TMS320C31. Each tool has its own version of the debugger. These versions 
operate almost identically; however, the executable files that invoke them are 
very different. For example, the EVM version won't work with the emulator or 
simulator, and vice versa. Separate commands are provided for invoking each 
version of the debugger. 


There are two debugger environments: the basic debugger environment and 
the profiling environment. The basic debugger environment is a 
general-purpose debugging environment. The profiling environment is a 
special environment for collecting statistics about code execution. Both 
environments have the same easy-to-use interface. 


Before you use this book, you should read the appropriate installation guide 
to install the C source debugger and any necessary hardware. 


How to Use This Manual 


The goal of this book is to help you learn to use the Texas Instruments 

advanced programmer’s interface for debugging. This book is divided into 

three distinct parts: 

(_} Part I: Hands-On Information is presented first so that you can start 
using your debugger the same day you receive it. 

HM Chapter 1 lists the key features of the debugger, describes additional 
’°C8x software tools, tells you how to prepare a ’C3x program for 
debugging, and provides instructions and options for invoking the 
debugger. 


M@ Chapter 2 is a tutorial that introduces you to many of the debugger 
features. 


How to Use This Manual 


(_} Part ll: Debugger Description contains detailed information about using 
the debugger. 


The chapters in Part II detail the individual topics that are introduced in the 
tutorial. For example, Chapter 3 describes all of the debugger’s windows 
and tells you how to move them and size them; Chapter 4 describes 
everything you need to know about entering commands. 


(_] Part Ill: Reference Material provides supplementary information. 


HM Chapter 11 provides a complete reference to all the tasks introduced 
in Parts | and Il. This includes a functional and an alphabetical 
reference of the debugger commands and a topical reference of 
function key actions. 


H@ Chapter 12 provides information about C expressions. The debugger 
commands are powerful because they accept C expressions as 
parameters; however, the debugger can also be used to debug 
assembly language programs. The information about C expressions 
will aid assembly language programmers who are unfamiliar with C. 


@ Part Ill also includes a glossary and an index. 


The way you use this book should depend on your experience with similar 
products. As with any book, it would be best for you to begin on page 1 and 
read to the end. Because most people don’t read technical manuals from cover 
to cover, here are some suggestions about what you should read. 


] Ifyou have used TI development tools or other debuggers before, then you 
may want to: 


M@ Read the introductory material in Chapter 1. 
HM Complete the tutorial in Chapter 2. 
HM Read through the alphabetical command reference in Chapter 11. 


[_] If this is the first time that you have used a debugger or similar tool, then 
you may want to: 


M@ Read the introductory material in Chapter 1. 
M@ Complete the tutorial in Chapter 2. 
M@ Read all of the chapters in Part Il. 


Notational Conventions 


Notational Conventions 


This document uses the following conventions. 


__] The TMS320C30 and TMS320C31 processors are referred to collectively 
as the ’C3x. 


[|_| The C source debugger has a very flexible command-entry system; there 


are a variety of ways to perform any specific action. For example, you may 
be able to perform the same action by typing in a command, using the 
mouse, or pressing function keys. There are three symbols to identify the 
methods that you can use to perform an action: 


Symbol 


Description 


Identifies an action that you perform by using the mouse. 


Identifies an action that you perform by using function keys. 


Identifies an action that you perform by typing in a 
command. 


_} The following symbols identify mouse actions. For simplicity, these 
symbols represent a mouse with two buttons. However, you can use a 
mouse with only one button or a mouse with more than two buttons. 


Symbol 
at 


I) 


0 
U 


Al) 


Action 


Point. Without pressing a mouse button, move the mouse to 
point the cursor at a window or field on the display. (Note that 
the mouse cursor displayed on the screen is not shaped like an 
arrow; it’s shaped like a block.) 


Press and hold. Press a mouse button. If your mouse has only 
one button, press it. If your mouse has more than one button, 
press the left button. 


Release. Release the mouse button that you pressed. 


Click. Press a mouse button and, without moving the mouse, 
release the button. 


Drag. While pressing the left mouse button, move the mouse. 
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Notational Conventions 


vi 


[_} Debugger commands are not case sensitive; you can enter them in 


lowercase, uppercase, or a combination. To emphasize this fact, 
commands are shown throughout this user’s guide in both uppercase and 
lowercase. 


Program listings and examples, interactive displays, and window contents 
are shown in a special font. Some examples use a bold version to identify 
code, commands, or portions of an example that you enter. Here is an 
example: 


Command Result displayed in the COMMAND window 
whatis giant struct zzz giant[100]; 
whatis xxx Struct. xxx { 

int a; 

int b; 

int -c; 


ant; £1. & “2% 
int £2 : 4; 
struct xxx *f3; 
int £4[10]; 

} 


In this example, the left column identifies debugger commands that you 
type in. The right column identifies the result that the debugger displays in 
the COMMAND window display area. 


In syntax descriptions, the instruction or command is in a bold face font, 
and parameters are in italics. Portions of a syntax that are in bold face 
should be entered as shown; portions of a syntax that are in italics 
describe the kind of information that should be entered. Here is an 
example of a command syntax: 


mem expression|, display format | 


mem is the command. This command has two parameters, indicated by 
expression and display format. The first parameter must be an actual C 
expression; the second parameter, which identifies a specific display 
format, is optional. 


Square brackets ( [ and ] ) identify an optional parameter. If you use an 
optional parameter, you specify the information within the brackets; you 
don’t enter the brackets themselves. Here’s an example of a command 
that has an optional parameter: 


run [expression] 


The RUN command has one parameter, expression, which is optional. 


Notational Conventions / Information About Cautions / Related Documentation From Texas Instruments 


_} Braces( {and} ) indicate alist. The symbol | (read as or) separates items 
within the list. Here’s an example of a list: 


sound {on | off} 
This provides two choices: sound on or sound off. 


Unless the list is enclosed in square brackets, you must choose one item 
from the list. 


Information About Cautions 


This is an example of a caution statement. 


A caution statement describes a situation that could potentially 


damage your software or equipment. 


Please read each caution statement carefully. 


Related Documentation From Texas Instruments 


The following books describe the TMS320C3x DSPs and related support 
tools. To obtain a copy of any of these Tl documents, call the Texas 
Instruments Literature Response Center at (800) 477-8924. When ordering, 
please identify the book by its title and literature number. 


TMS320C3x User’s Guide (literature number SPRU031) describes the 'C3x 
32-bit floating-point microprocessor (developed for digital signal 
processing as well as general applications), its architecture, internal 
register structure, instruction set, pipeline, specifications, and DMA and 
serial port operation. Software and hardware applications are included. 

TMS320 Floating-Point DSP Assembly Language Tools User’s Guide 
(literature number SPRUO35) describes the assembly language tools 
(assembler, linker, and other tools used to develop assembly language 
code), assembler directives, macros, common object file format, and 
symbolic debugging directives for the ‘C3x and ’C4x generations of 
devices. 

TMS320 Floating-Point DSP Optimizing C Compiler User’s Guide 
(literature number SPRU024) describes the TMS320 floating-point C 
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TMS320C30 Evaluation Module Technical Reference (literature number 
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If you are an assembly language programmer and would like more information 
about C or C expressions, you may find this book useful: 


The C Programming Language (second edition, 1988), by Brian W. 
Kernighan and Dennis M. Ritchie, published by Prentice-Hall, Englewood 
Cliffs, New Jersey. 
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PC-DOS and OS/2 are trademarks of International Business Machines Corp. 
MS-DOS and MS-Windows are registered trademarks of Microsoft Corp. 
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Chapter 1 


Overview of a Code 
Development and Debugging System 


The TMS320C8x C source debugger is an advanced programmer’s interface 
that helps you to develop, test, and refine ’C3x C programs (compiled with the 
’C83x optimizing ANSI C compiler) and assembly language programs. The de- 
bugger is the interface to the ’C3x simulator, EVM, and unique scan-based, 
realtime emulator. 


This chapter gives an overview of the programmer’s interface, describes the 
’°C8x code development environment, and provides instructions and options 
for invoking the debugger. 
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Description of the ‘C3x C Source Debugger 


1.1. Description of the ’C3x C Source Debugger 


Figure 1-1. 


The ’C3x C source debugger interface improves productivity by allowing you 
to debug a program in the language it was written in. You can choose to debug 
your programs in C, assembly language, or both. And, unlike many other de- 
buggers, the ’C3x debugger’s higher level features are available even when 
you’re debugging assembly language code. 


The Texas Instruments advanced programmer’s interface is easy to learn and 
use. Its friendly window-, mouse-, and menu-oriented interface reduces learn- 
ing time and eliminates the need to memorize complex commands. The de- 
bugger’s customizable displays and flexible command entry let you develop 
a debugging environment that suits your needs—you won't be locked into a 
rigid environment. A shortened learning curve and increased productivity re- 
duce the software development cycle, so you'll get to market faster. 


Figure 1-1 identifies several features of the debugger display. 


The Basic Debugger Display 
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Description of the ‘C3x C Source Debugger 


Key features of the debugger 


_} Multilevel debugging. The debugger allows you to debug both C and as- 
sembly language code. If you’re debugging a C program, you can choose 
to view just the C source, the disassembly of the object code created from 
the C source, or both. You can also use the debugger as an assembly lan- 
guage debugger. 


(_} Fully configurable, state-of-the-art, window-oriented interface. The 
C source debugger separates code, data, and commands into manage- 
able portions. Use any of the default displays. Or, select the windows you 
want to display, size them, and move them where you want them. 


[_} Comprehensive data displays. You can easily create windows for dis- 
playing and editing the values of variables, arrays, structures, pointers— 
any kind of data—in their natural format (float, int, char, enum, or pointer). 
You can even display entire linked lists. 


= : --WATCH 
DISP: str — | 


a 123 A Destro 
iy (0) ' 2: FO 1.000000e 
c¢ 75435/DISP: *str.£3 — 3: color GREEN 
rai} a 8327 A 
£2 6 b 666 ! 
£3 Ox00f| c 87213,DISP: *str.£3->f3 al 
fA [feenil || ab 2G a 75 A 
£22) be s2t2 
£3 Ox00f| ¢ 782 | 
£4 soilless a 
: f2 9 v 
£3 0x00f000a 
a £4 [...-] 


[_] On-screen editing. Change any data value displayed in any window— 
just point the mouse, click, and type. 


[|_| Continuous update. The debugger continuously updates information on 
the screen, highlighting changed values. 


(_} Powerful command set. Unlike many other debugging systems, this de- 
bugger doesn’t force you to learn a large, intricate command set. The ’C3x 
C source debugger supports a small but powerful command set that 
makes full use of C expressions. One debugger command performs ac- 
tions that would take several commands in another system. 
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(_] Flexible command entry. There are a variety of ways to enter com- 


mands. You can type commands or use a mouse, function keys, or the 
pulldown menus; choose the method that you like best. Want to re-enter 
a command? No need to retype it—simply use the command history. 


Create your own debugger. The debugger display is completely confi- 
gurable, allowing you to create the interface that is best suited for your use. 


HM If you’re using a color display, you can change the colors of any area 
on the screen. 


M You can change the physical appearance of display features such as 
window borders. 


M@ You can interactively set the size and position of windows in the dis- 
play. 


Create and save as many custom configurations as you like, or use the 
defaults. Use the debugger with a color display or a black-and-white dis- 
play. A color display is preferable; the various types of information on the 
display are easier to distinguish when they are highlighted with color. 


Variety of screen sizes. The debugger’s default configuration is set up 
for atypical PC display, with 25 lines by 80 characters. If you use a sophis- 
ticated graphics card, you can take advantage of the debugger’s addition- 
al screen sizes. A larger screen size allows you to display more informa- 
tion and provides you with more screen space for organizing the display— 
bringing the benefits of workstation displays to your PC. 


All the standard features you expect in a world-class debugger. The 
debugger provides you with complete control over program execution with 
features like conditional execution and single-stepping (including single- 
stepping into or over function calls). You can set or clear a breakpoint with 
a Click of the mouse or by typing commands. You can define a memory 
map that identifies the portions of target memory that the debugger can 
access. You can choose to load only the symbol table portion of an object 
file to work with systems that have code in ROM. The debugger can 
execute commands from a batch file, providing you with an easy method 
for entering often-used command sequences. 


Description of the Profiling Environment 


1.2 Description of the Profiling Environment 


In addition to the basic debugging environment, a second environment—the 
profiling environments available. The profiling environment provides a 
method for collecting execution statistics about specific areas in your code. 
This gives you immediate feedback on your application’s performance. The 
profiler is not available when you're running the debugger under DOS. 


Figure 1—2 identifies several features of the debugger display within the profil- 
ing environment. 


Figure 1-2. The Profiling-Environment Display 


profiling areas 
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PROFILE ——> 
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execution 
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pulldown menu 
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‘COMMAND 
65 symbols loaded 


Done 


file sample.c 


>>> fl 


FILE: 
00053 
00054 
00055 
00056 
00057 
00058 
00059 
00060 
00061 
00062 
00063 
00064 
00065 
00066 


sample.c 


main () 


{ 


LE> meminit (); 
for (i = 0; 


RE> 
{ 


<< 


iene (98) 


register in 
int j = 0, 


i < 0x50000; 


eae (a3): 

if (i & 5) 5 += i; 
aai[k][k] = j; 

if (!(i & OxFFFF) ) v 


Key features of the profiling environment 


profiling areas 
are clearly 
marked 


The profiling environment builds on the same easy-to-use interface available 
in the basic debugging environment and provides these additional features: 


_] More efficient code. Within the profiling environment, you can quickly 
identify busy sections in your programs. This helps you to direct valuable 
development time toward streamlining the sections of code that most dra- 
matically affect program performance. 
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_] Statistics on multiple areas. You can collect statistics about individual 


statements in disassembly or C, about ranges in disassembly or C, and 
about C functions. When you are collecting statistics on many areas, you 
can choose to view the statistics for all the areas or a subset of the areas. 


Comprehensive display of statistics. The profiler provides all the in- 
formation you need for identifying bottlenecks in your code: 


HM The number of times each area was entered during the profiling ses- 
sion. 


The total execution time of an area, including or excluding the execu- 
tion time of any subroutines called from within the area. 


M@ The maximum time for one iteration of an area, including or excluding 
the execution time of any subroutines called from within the area. 


Statistics may be updated continuously during the profiling session or at 
selected intervals. 


Configurable display of statistics. Display the entire set of data, or dis- 
play one type of data at a time. Display all the areas you’re profiling, or dis- 
play a selected subset of the areas. 


Visual representation of statistics. When you choose to display one 
type of data at a time, the statistics will be accompanied by histograms for 
each area, showing the relationship of each area’s statistics to those of the 
other profiled areas. 


Disabled areas. |n addition to identifying areas that you can collect statis- 
tics on, you can also identify areas that you don’t want to affect the statis- 
tics. This removes the timing impact from code such as a standard library 
function or a fully optimized portion of code. 


Special profiling commands. The profiling environment supports a rich 
set of commands to help you select areas and display information. Some 
of the basic debugger commands—such as the memory map com- 
mands—may be necessary during profiling and are available within the 
profiling environment. Other commands—such as breakpoint commands 
and run commands—are not necessary and are therefore not available 
within the profiling environment. 


Developing Code for the ’C3x 


1.3 Developing Code for the ’C3x 


The ’C3x is well supported by a complete set of hardware and software devel- 
opment tools, including a C compiler, assembler, and linker. Figure 1—3 illus- 
trates the ’C3x code development flow. The most common paths of software 
development are highlighted in grey; the other portions are optional. 


Figure 1-3. 'C3x Software Development Flow 
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These tools use common object file format (COFF), which encourages modu- 
lar programming. COFF allows you to divide your code into logical blocks, de- 
fine your system’s memory map, and then link code into specific memory 
areas. COFF also provides rich support for source-level debugging. 


The following list describes the tools shown in Figure 1-3. 


The ’C3x optimizing ANSI C compiler is a full-featured optimizing compiler 
that translates standard ANSI C programs into ’C3x assembly language 


source. Key characteristics include: 


(_] Standard ANSI C. The ANSI standard is a precise definition of the C lan- 


guage, agreed upon by the C community. The standard encompasses 
most of the recent extensions to C. To an increasing degree, ANSI confor- 
mance is a requirement for C compilers in the DSP community. 


Optimization. The compiler uses several advanced techniques for gener- 
ating efficient, compact code from C source. 


Assembly language output. The compiler generates assembly lan- 
guage source that you can inspect (and modify, if desired). 


ANSI standard runtime support. The compiler package comes with a 
complete runtime library that conforms to the ANSI C library standard. The 
library includes functions for string manipulation, dynamic memory alloca- 
tion, data conversion, timekeeping, trigonometry, exponential operations, 
and hyperbolic functions. Functions for I/O and signal handling are not in- 
cluded, because they are application specific. 


Flexible assembly language interface. The compiler has straightfor- 
ward calling conventions, allowing you to easily write assembly and C 
functions that call each other. 


Shell program. The compiler package includes a shell program that en- 
ables you to compile, assemble, and link programs in a single step. 


Source interlist utility. The compiler package includes a utility that 
interlists your original C source statements into the assembly language 
output of the compiler. This utility provides you with an easy method for 
inspecting the assembly code generated for each C statement. 


assembler 


debugging 
tools 


hex 
conversion 
utility 


Developing Code for the ’C3x 


The assembler translates ’C3x assembly language source files into machine 
language object files. 


The linker combines object files into a single, executable object module. As 
the linker creates the executable module, it performs relocation and resolves 
external references. The linker is a tool that allows you to define your system’s 
memory map and to associate blocks of code with defined memory areas. 


The main purpose of the development process is to produce a module that can 
be executed in a ’C3x target system. You can use one of several debugging 
tools to refine and correct your code. Available products include: 

(J A realtime in-circuit emulator, 

[__.} An evaluation module (EVM), and 

_} A software simulator. 


A hex conversion utility is also available; it converts a COFF object file into 
an ASCII-Hex, Intel, Motorola-S, Tektronix, or Tl-tagged object-format file that 
can be downloaded to an EPROM programmer. 
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1.4 Preparing Your Program for Debugging 


Figure 1—4 illustrates the steps you must go through to prepare a program for 
debugging. 


Figure 1-4. Steps You Go Through to Prepare a Program 


If you’re working with a C | 
program, start here Cc 
source 
C Compiler 


If you're working with an : assembly 
assembly language : language 


program, start here * code 
Assembler 


This is the file that you load 7 


: sexecutable. 
when you invoke the ‘object code 
debugger : : 


If you’re preparing to 1) Compile the program; use the —g option. If you 
debug aC program. .. plan to use the profiler, compile the program with 
the —as option. 


2) Assemble the resulting assembly language pro- 
gram. 


3) Link the resulting object file. 
This produces an object file that you can load into the 
debugger. 
If you’re preparing to 1) Assemble the assembly language source file. 


debug an assembly 


2) Link the resulting object file. 
language program... 


This produces an object file that you can load into the 
debugger. 


You can compile, assemble, and link a program by invoking the compiler, as- 
sembler, and linker in separate steps, or you can perform all three actions in 
asingle step by using the cl30 shell program. The TMS320 Floating-Point DSP 
Assembly Language Tools User’s Guide and TMS320 Floating-Point DSP Op- 
timizing C Compiler User’s Guide contain complete instructions for invoking 
the tools individually and for using the shell program. 


Preparing Your Program for Debugging 


For your convenience, here’s the command for invoking the shell program 
when preparing a program for debugging: 


cl30 [-options] -g [filenames] [-z [link options]] 


cl30 


options 


filenames 


-9 


—Z 


link options 


is the command that invokes the compiler and assembler. 


affect the way the shell processes input files. If you plan to use 
the debugger’s profiling environment, include the —as option. 


are one or more C source files, assembly language source files, 
or object files. Filenames are not case sensitive. 


is an option that tells the C compiler to produce symbolic debug- 
ging information. When preparing a C program for debugging, 
you must use the —g option. 


is an option that invokes the linker. After compiling/assembling 
your programs, you can invoke the linker in a separate step. If 
you want the shell to automatically invoke the linker, however, 
use —Z. 


affect the way the linker processes input files; use these options 
only when you use —z. 


Options and filenames can be specified in any order on the command line, but 
if you use —z, it must follow all C/assembly language source filenames and 
compiler options. 


The shell identifies a file’s type by the filename’s extension. 


Extension File Type File Description 

Cc C source compiled, assembled, 
and linked 

.asm assembly language assembled and linked 

source 

.S* (any extension that assembly language assembled and linked 

begins with s) source 

.o* (extension begins object file linked 

with 0) 

none (.c assumed) C source compiled, assembled, 
and linked 
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1.5 Invoking the Debugger 


Here’s the basic format for the commands that invoke the debugger: 


emulator: emu3x [filename] [—options] 
> EVM: evm30 [filename] [—options] 
simulator: sim3x_ [filename] [—options] 


emu3x, evm30 
sim3x are the commands that invoke the debugger. 


filename is an optional parameter that names an object file that the de- 
bugger will load into memory during invocation. The debug- 
ger looks for the file in the current directory; if the file isn’tin the 
current directory, you must supply the entire pathname. If you 
don’t supply an extension for the filename, the debugger as- 
sumes that the extension is .out, unless you’re using multiple 
extensions; you must specify the entire filename if the file- 
name has more than one extension. 


—options supply the debugger with additional information (Table 1-1 
summarizes the available options). 


You can also specify filename and option information with the D_. OPTIONS en- 
vironment variable (see Setting up the environment variables in the appropri- 
ate installation guide). Table 1-1 lists the debugger options and specifies 
which debugger tools use the options; the subsections following the table de- 
scribe the options. 


Table 1-1. Summary of Debugger Options 


Option Brief description Debugger Tools 

—b[b] Select the screen size All 

—i pathname Identify additional directories All 

—mmmode Select the operating mode Simulator 

—mvversion Select the device version Simulator 

—p port address Identify the port address EVM and emulator 

—profile Enter the profiling environment All, except when running 
under DOS 

-Ss Load the symbol table only All 

—t filename Identify a new initialization file All 

—V Load without the symbol table All 

-Xx Ignore DLOPTIONS All 


Invoking the Debugger 


Selecting the screen size (—b option) 


By default, the debugger uses an 80-character-by-25-line screen. You can use 
one of the options in Table 1—2 to specify a different screen size. On Sun sys- 
tems, you can resize the screen at runtime also. 


Table 1-2. Screen Size Options 


Option Description Display 

none 80 characters by 25 lines Default display 

—b 80 characters by 43 lines Any EGA or VGA display 
—bb 80 characters by 50 lines VGA only 


SPT | 


Note: 


On Sun systems, the maximum size of the debugger screen is 132 charac- 
ters by 60 lines. 


a 


Identifying additional directories (-i option) 


The —i option identifies additional directories that contain your source files. Re- 
place pathname with an appropriate directory name. You can specify several 
pathnames; use the -i option as many times as necessary. For example: 


emu3x -i pathname; -i pathnameo -i pathname3... 


Using —i is similar to using the D_SRC environment variable (see Setting up 
the environment variables in the appropriate installation guide). If you name 
directories with both —i and D_SRC, the debugger first searches through direc- 
tories named with —i. The debugger can track a cumulative total of 20 paths 
(including paths specified with —i, D_SRC, and the debugger USE commana). 


Selecting the operating mode (—mm option) 


The —mm option is valid only when you are using the simulator. The -mm op- 
tion tells the simulator to operate in either the microprocessor or microcomput- 
er mode: 


—mm0 _ tells the simulator to operate in the microprocessor mode. 
—mm_1_ tells the simulator to operate in the microcomputer mode (default). 


If you don’t use the —mm option, the simulator operates in the microcomputer 
mode. 


Overview of a Code Development and Debugging System 1-13 


Invoking the Debugger 


Selecting the device version (—mv option) 


The —mv option is valid only when you are using the simulator. The —mv option 
tells the simulator to simulate the ’C30 or the ‘C31 memory map: 


—mv30_ tells the simulator to simulate the C30 memory map (default). 
—mv31_ tells the simulator to simulate the C31 memory map. 


If you don’t use the —mv option, the simulator simulates the C30 memory map. 


Identifying the port address (-p option) 


The -p option is valid only when you are using the EVM or emulator. The —p 
option identifies the I/O port address that the debugger uses for communicat- 
ing with the emulator or EVM. If you used the default switch settings, you don’t 
need to use the—p option. If you used nondefault switch settings, you must 
use —p. Refer to your entries in the Your Settings table in the appropriate instal- 
lation guide; depending on your switch settings, replace port address with one 
of these values: 


Switch 1 Switch 2 Option 
on on —p 240 (optional) 
on off —p 280 
off on —p 320 
off off —p 340 


If you didn’t note the I/O switch settings, you can use a trial-and-error approach 
to find the correct —p setting. If you use the wrong setting, you will see an error 
message when you invoke the debugger. (See the appropriate installation 
guide for more information.) 


Entering the profiling environment (—profile option) 


This option is not valid when you’re running the debugger under DOS. The — 
profile option allows you to bring up the debugger in a profiling environment 
so that you can collect statistics about code execution. Note that only a subset 
of the basic debugger features is available in the profiling environment. 


Loading the symbol table only (-s option) 


If you supply a filename when you invoke the debugger, you can use the —s 
option to tell the debugger to load only the file’s symbol table (without the file’s 
object code). This is similar to loading a file by using the debugger’s SLOAD 
command. 


Invoking the Debugger / Exiting the Debugger 


Identifying a new initialization file (-t option) 


The -t option allows you to specify an initialization command file that will be 
used instead of init.cmd. The format for this option is: 


-t filename 


Loading without the symbol table (—v option) 


The —v option prevents the debugger from loading the entire symbol table 
when you load an object file. The debugger loads only the global symbols and 
later loads local symbols as it needs them. This speeds up the loading time and 
consumes less memory space. 


The —-v option affects all loads, including those performed when you invoke the 
debugger and those performed with the LOAD command within the debugger 
environment. 


Ignoring D_OPTIONS (-x option) 


The —x option tells the debugger to ignore any information supplied with D_OP- 
TIONS. For more information about D_OPTIONS, refer to the appropriate 
installation guide. 


1.6 Exiting the Debugger 


To exit any version of the debugger and return to the operating system, enter 
this command: 


quit 


You don’t need to worry about where the cursor is or which window is ac- 
tive—just type. If a program is running, press to halt program execution 
before you quit the debugger. 


If you are running the debugger under MS-Windows, you can also exit the de- 
bugger by selecting the exit option from the MS-Windows menu bar. 
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Debugging ’C3x Programs 


1.7 Debugging ’C3x Programs 
Debugging a program is a multiple-step process. These steps are described 
below, with references to parts of this book that will help you accomplish each 
step. 


Step 1 


Prepare a C program or as- See Section 1.4, Preparing 
sembly language program for Your Program for Debug- 
debugging. ging, page 1-10. 

BS} (<) 0) 
Ensure that the debugger has See Chapter 5, Defining a 
a valid memory map. Memory Map. 

BS} (<) oe) 
Load the program's object file. See Section 6.3, Loading 

Object Code, page 6-10. 
BS) (=) oye} 


Runtheloadedfile. Youcanrun See Running Your Programs 
the entire program, run parts of on page 6-12. 


the program, or single-step 
through the program. 


Stop the program at critical See Chapter 8, Using 


points and examine important Software Breakpoints, and 
information Chapter 7, Managing Data. 


If you find minor problems in See Modifying assembly lan- 


your code, you can temporari- guage code on page 6-5. 
ly solve them with patch as- 


Once you have decided what changes must be made to your 
program, exit the debugger, edit your source file, and return to 
Step 1. 


(Od a T=] 0) (=) a 


An Introductory Tutorial 
to the C Source Debugger 


This chapter provides a step-by-step, hands-on demonstration of the ’'C3x C 
source debugger’s basic features. This is not the kind of tutorial that you can 
take home to read—tt is effective only if you're sitting at your terminal, perform- 
ing the lessons in the order that they’re presented. The tutorial contains two 
sets of lessons (11 in the first, 13 in the second) and takes about one hour to 
complete. 


Topic Page 
How to use this tutorial 2-2 
A note about entering commands 2-2 
An escape route (just in case) 2-3 
Invoke the debugger and load the sample program’s object code 2-3 
Take a look at the display... 2-4 
Whai’s in the DISASSEMBLY window? 2-5 
Select the active window 2-5 
Size the active window 2-7 
Zoom the active window 2-8 
Move the active window 2-9 
Scroll through a window’s contents 2-10 
Display the C source version of the sample file 2-11 
Execute some code 2-11 
Become familiar with the three debugging modes 2-12 
Open another text file, then redisplay a C source file 2-14 
Use the basic RUN command 2-14 
Set some breakpoints 2-15 
Watch some values and single-step through code 2-16 
Run code conditionally 2-18 
WHATIS that? 2-19 
Clear the COMMAND window display area 2-20 
Display the contents of an aggregate data type 2-20 
Display data in another format 2-23 
Change some values 2-25 
Define a memory map 2-26 
Define your own command string 2-27 
Close the debugger 2-27 
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How to Use This Tutorial / A Note About Entering Commands 


How to use this tutorial 


This tutorial contains three basic types of information: 


Primary actions Primary actions identify the main lessons in the 
tutorial; they're boxed so that you can find them 
easily. A primary action looks like this: 


Make the CPU window the active window: 


win CPU 


Important information In addition to primary actions, important in- 
formation ensures that the tutorial works cor- 
rectly. Important information is marked like this: 


The CPU window should still be 
active from the previous step. 


Alternative actions Alternative actions show additional methods for 
performing the primary actions. Alternative ac- 
tions are marked like this: 


Try This: | Another way to display the current 
code in MEMORY is to show memory begin- 
ning from the current PC. . . 


| Important! | This tutorial assumes that you have correctly and completely 
installed your debugger (including invoking any files or DOS commands as 
instructed in the installation guide). 


A note about entering commands 
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Whenever this tutorial tells you to type a debugger command, just type—the 
debugger automatically places the text on the command line. You don’t have 
to worry about moving the cursor to the command line; the debugger takes 
care of this for you. (There are a few instances when this isn’t true—for exam- 
ple, when you're editing data in the CPU or MEMORY window—but this is ex- 
plained later in the tutorial.) 


Also, you don't have to worry about typing commands in uppercase or lower- 
case—either is fine. There are a few instances when acommand'’s parameters 
must be entered in uppercase, and the tutorial points this out. 


An Escape Route / Invoke the Debugger and Load the Sample Program's Object Code 


An escape route (just in case) 


The steps in this tutorial create a path for you to follow. The tutorial won't pur- 
posely lead you off the path. But sometimes when people use new products, 
they accidently press the wrong key, push the wrong mouse button, or mistype 
a command. Suddenly, they’re off the path without any idea of where they are 
or how they got there. 


This probably won’t happen to you. But, if it does, you can almost always get 
back to familiar ground by pressing . If you were running a program when 
you pressed (ESC), you should also type RESTART @). Then go back to the 
beginning of whatever lesson you were in and try again. 


Invoke the debugger and load the sample program’s object code 


Included with the debugger is a demonstration program named sample. This 
lesson shows you how to invoke the debugger and load the sample program. 
You will use the —b option so that the debugger uses a larger display. 


Note: 


The —b option is not supported with the VAX/VMS version of the simulator. 


| Important! | When using the emulator or EVM, this step assumes that you are 
using the default I/O address or that you have identified the I/O address with 
the D_OPTIONS environment variable (as described in the individual installa- 
tion guides). 


Invoke the debugger and load the sample program: 
For the emulator, enter: 
emu3x -b c:\c3xhl1\sample 


For the EVM, enter: 


evm30 -b c:\c3xhl1\sample (2) 


For the simulator, enter: 


sim3x -b c:\sim3x\sample 
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Take a Look at the Display 


Take a look at the display. . . 


Now you should see a display similar to this. The code should be the same on 
your screen, but your window sizes may vary. 


menu bar with ——__> fer Break Watch Memory Color MoDe Pin Run=F5 Step=F8 Next=F10 
pulldown menus [— DISASSEMBLY a pce i 
80985d 00809938 ABS1 IOF,RO PC 0080985e 
current PC res Tsv000Sc_int00: DI 0,ST SP 00000755 
(highlighted) 80985£ 50700080 LDIU =: 128, DP RO 00000003 
809860 0834985c LDI &0f0985cH, SP R1 00000005 
809861 080b0014 LDI SP, AR3 R2 00000007 
809862 50700080 LDIU 128, DP R3 00000000 
809863 0828985d LDI &0£0985dH, ARO R4 00000000 
reverse assembly ————Sp809864 O4esreet CMPI  -1,ARO R5 00000000 
809865 6a05000d BZ 0809873H R6 00000000 
of memory contents 809866 08402001 LDI *ARO++ (1) ,RO R7 00000000 
809867 6a250009 BZD 0809873H ARO 00001802 
register contents Beneeseaunns 
809869 08492001 LDI *ARO++ (1) ,ARL AR2 00000000 
80986a 08402001 LDI *ARO++ (1) ,RO AR3 00000000 
80986b 187b0001 SUBI 1,RC AR4 00000000 
80986c 6480986d RPTB 080986dH AR5 00000000 
80986d da002120 LDI *ARO++(1),RO || STI RO,*AR AR6 00000000 
80986e 04200000 CMPI  0,RO AR7 00000000 
80986£ 6a26ff£9 BNZD  080986bH IRO 00000000 
809870 081b0000 LDI RO,RC IR1 00000000 
809871 08492001 LDI *ARO++ (1) ,ARL ST 00000000 
809872 08402001 LDI *ARO++ (1) ,RO ! RC 00000000 | 
‘COMMAND: MEMORY ; 
i Copyright (c) 1989, 1993 Texas In 000000 0000004b 00000040 00000041 00000042 g@ 
COMMAND window — >] 0 s:0cae 000004 00000043 ©00000044 + 00000045 + 00000046 
display area : ‘ 000008 00000047 00000048 00000049 0000004a 
simulacorgverstong2- OT 00000c 00000000 00000000 00000000 00000000 
Loading sample.out 009010 00000000 00000000 00000000 00000000 
memory contents B14 00000000 00000000 + 00000000 + -00000000 » 
000018 00000000 00000000 00000000 00000000 
command line 00001c 00000000 00000000 00000000 00000000 
000020 00000000 00000000 _00000000 _ 00000000 


_] If you don’t see a display, then your debugger or board may not be 
installed properly. Go back through the installation instructions and be 
sure that you followed each step correctly; then reinvoke the debugger. 


I 


If you do see a display, check the first few lines of the DISASSEMBLY win- 


dow. If these lines aren’t the same—if, for example, they show ADD 
instructions or say Invalid address—then enter the following commands 
on the debugger command line. (Just type; you don’t have to worry about 


where the cursor is.) 
1) 

reset 
2) 


Reset the 'C3x processor: 


Load the sample program again: 


load c:\c3xh11\sample (emulator and EVM) 
load c:\sim3x\sample (simulator) 


After reset, if you see adisplay and the first few lines of the DISASSEMBLY 


window still show ADD instructions or say /nvalid address, your EVM or 
emulator board may not be installed snugly. Check your board to see if it 
is correctly installed, and re-enter the commands above. 
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What's in the DISASSEMBLY Window? / Select the Active Window 


What’s in the DISASSEMBLY window? 


The DISASSEMBLY window always shows the reverse assembly of memory 
contents; in this case, it shows an assembly language version of sample.out. 
The MEMORY window displays the current contents of memory. Because you 
loaded the object file sample.out when you invoked the debugger, memory 
contains the object code version of the sample file. 


This tutorial step demonstrates that the code shown in the DISASSEMBLY 
window corresponds to memory contents. Initially, memory is displayed start- 
ing at address 0; if you look at the first line of the DISASSEMBLY window, you'll 
see that its display starts at address 0x0080 985d. 


Modify the MEMORY display to show the same object code that is dis- 
played in the DISASSEMBLY window: 


mem 0x80985d 


Notice that the first column in the DISASSEMBLY window corresponds to the 
addresses in the MEMORY window; the second column inthe DISASSEMBLY 
window corresponds to the memory contents displayed in the MEMORY win- 
dow. 


Try This: | The highlighted statement in the DISASSEMBLY window shows 
that the PC is currently pointing to address 0x0080 985e. You can modify the 
MEMORY display to show memory beginning from the current PC: 


mem PC 


Select the active window 


This lesson shows you how to make a window the active window. You can 
move and resize any window; you can close some windows. Whenever you 
type a command or press a function key to move, resize, or close a window, 
the debugger must have some method of understanding which window you 
want to affect. The debugger does this by designating one window at a time 
to be the active window. Any window can be the active window, but only one 
window at a time can be active. 


lesson continues on the next page > 
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Select the Active Window 
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(i 


Make the CPU window the active window: 


win CPU 


| Important! | Notice the appearance of the CPU window (especially its bor- 
ders) in contrast to the other, inactive windows. This is how you can tell which 
window is active. 


| Important! | If you don’t see a change in the appearance of the CPU window, 
look at the way you entered the command. Did you enter CPU in uppercase 
letters? For this command, it’s important that you enter the parameter in upper- 
case, as shown. 


Try This: 


Press the key to “cycle” through the windows in the display, 
making each one active in turn. Press as many times as necessary until 
the CPU window becomes the active window. 


Try This: 


You can also use the mouse to make a window active: 


1) Point to any location on the window’s border. 


2) Click the left mouse button. 


Be careful! If you point inside the window, the window becomes active when 
you press the mouse button, but something else may happen as well: 


_] If you’re pointing inside the CPU window, then the register you're pointing 
at becomes active. The debugger then treats the text you type as a new 
value for that register. Similarly, if you’re pointing inside the MEMORY win- 
dow, the address you're pointing at becomes active. 


Press to get out of this. 


_] If you’re pointing inside the DISASSEMBLY or FILE window, you'll set a 
breakpoint on the statement that you were pointing to. 


To delete the breakpoint, point to the same statement and press the 
mouse button again. 


Size the Active Window 


Size the active window 


A 


UU 


This lesson shows you how to resize the active window. 


| Important! | The CPU window should still be active from the previous step. 


Make the CPU window as small as possible: 


size 4,3 


This tells the debugger to make the window 4 characters by 3 lines, which is 
the smallest a window can be. (If it were any smaller, the debugger wouldn't 
be able to display all four corners of the window.) If you try to enter smaller val- 
ues, the debugger will warn you that you’ve entered an Invalid window size. 
The maximum width and length depend on which screen-size option you used 
when you invoked the debugger. 


Make the CPU window larger: 
size Enter the SIZE command without parameters 
C+] Make the window 3 lines longer 


Make the window 4 characters wider 


ESC Press this key when you finish sizing the window 


You can use @) to make the window shorter and © to make the window nar- 
rower. 


Try This: | You can use the mouse to resize the window (note that this process 
forces the selected window to become the active window). 


1) If you examine any window, you'll see a highlighted, backwards “L” in the 
lower right corner. Point to the lower right corner of the CPU window. 


2) Press the left mouse button, but don’t release it; move the mouse while 
you're holding in the button. This resizes the window. 


3) Release the mouse button when the window reaches the desired size. 
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Zoom the Active Window 


Zoom the active window 


Another way to resize the active window is to zoom it. Zooming the window 
makes it as large as possible. 


| Important! | The CPU window should still be active from the previous steps. 


E} Make the active window as large as possible: 


zoom 


The window should now be as large as possible, taking up the entire display 
(except for the menu bar) and hiding all the other windows. 


“Unzoom’ or return the window to its previous size by entering the ZOOM 
command again: 


zoom The ZOOMcommand will be recognized, 
even though the COMMAND window is hidden 
by the CPU window. 


The window should now be back to the size it was before zooming. 


S Try This: | You can use the mouse to zoom the window. 


Zoom the active window: 


KR 1) Point to the upper left corner of the active window. 


10 2) Click the left mouse button. 


Return the window to its previous size by repeating these steps. 
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Move the Active Window 


Move the active window 


UU 


This lesson shows you how to move the active window. 


| Important! | The CPU window should still be active from the previous steps. 


Move the CPU window to the upper left portion of the screen: 


move 0,1 The debugger doesn't let you move the window 
to the very top—that would hide the menu bar 


The MOVE command's first parameter identifies the window’s new X position 
on the screen. The second parameter identifies the window’s new Y position 
on the screen. The maximum X and Y positions depend on which screen-size 
option you used when you invoked the debugger and on the position of the win- 
dow before you tried to move it. 


Try This: | You canuse the MOVE command with no parameters and then use 
arrow keys to move the window: 


move 
Press @) until the CPU window is back where it was 
(it may seem like only the border is moving—this is normal) 
ESC Press when you finish moving the window 


You can also use @) to move the window up, @ to move the window down, 
and ©) to move the window left. 


Try This: | You can use the mouse to move the window (note that this process 
forces the selected window to become the active window). 


1) Point to the top edge or left edge of the window border. 


2) Press the left mouse button, but don’t release the button; move the mouse 
while you're holding in the button. 


3) Release the mouse button when the window reaches the desired position. 
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Scroll Through a Window’s Contents 


Scroll through a window’s contents 


Many of the windows contain more information than can possibly be displayed 
at one time. You can view hidden information by moving through a window’s 
contents. The easiest way to do this is to use the mouse to scroll the display 
up or down. 


If you examine most windows, you'll see an up arrow near the top of the right 
border and a down arrow near the bottom of the right border. These are scroll 
arrows. 


Scroll through the contents of the DISASSEMBLY window: 


Point to the up or down scroll arrow. 


Press the left mouse button; continue pressing it until the dis- 
play has scrolled several lines. 


Release the button. 


Try This: 


window. 


You can use several of the keys to modify the display in the active 


Make the MEMORY window the active window: 

win MEMORY 

Now try pressing these keys; observe their effects on the window’s contents. 
e3) an) 


These keys don’t work the same for all windows; Section 11.5 (page 11-52) 
summarizes the functions of all the special keys, key sequences, and how they 
affect different windows. 


Display the C Source Version of the Sample File / Execute Some Code 


Display the C source version of the sample file 


Now that you can find your way around the debugger interface, you can be- 
come familiar with some of the debugger’s more significant features. It’s time 
to load some C code. 


Display the contents of a C source file: 


file sample.c 


This opens a FILE window that displays the contents of the file sample.c 
(sample.c was one of the files that contributed to making the sample object 
file). You can always tell which file you’re displaying by the label in the FILE 
window. Right now, the label should say FILE: sample.c. 


Execute some code 


Let’s run some code—not the whole program, just a portion of it. 


Execute a portion of the sample program: 


go main 


You've just executed your program up to the point where main() is declared. 
Notice how the display has changed: 


[_| The current PC is highlighted in both the DISASSEMBLY and FILE win- 
dows. 


[_.] The addresses and object codes of four statements in the DISASSEMBLY 
window are highlighted; this is because these statements are associated 
with the current C statement (line 33 in the FILE window). 


[_.] The CALLS window, which tracks functions as they’re called, now points 
to main(). 


[_.] The values of the PC and SP (and possibly some additional registers) are 
highlighted in the CPU window because they were changed by program 
execution. 
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Become Familiar With the Three Debugging Modes 


Become familiar with the three debugging modes 
The debugger has three basic debugging modes: 
[|_| Mixed mode shows both disassembly and C at the same time. 


[|_| Auto mode shows disassembly or C, depending on what part of your pro- 
gram happens to be running. 


[_| Assembly mode shows only the disassembly, no C, even if you’re 
executing C code. 


When you opened the FILE window in a previous step, the debugger switched 
to mixed mode; you should be in mixed mode now. (You can tell that you’re in 
mixed mode if both the FILE and DISASSEMBLY windows are displayed.) 


The following steps show you how to switch debugging modes. 


S Use the MoDe menu to select assembly mode: 


Look at the top of the display: the first line shows a row of pull- 
down menu selections. 


Point to the word MoDe on the menu bar. 


Press the left mouse button, but don’t release it; drag the 
mouse downward until Asm (the second entry) is highlighted. 


Release the button. 


This switches to assembly mode. You should see the DISASSEMBLY window, 
but not the FILE window. 


Switch to auto mode: 
1) Press [(a:t)[p}. This displays and freezes the MoDe menu. 


2) Now select C(auto). To do so, choose one of these methods: 


1 Press the arrow keys to move up/down through the menu; when 
C(auto) is highlighted, press (2). 


Type C. 


Point the mouse cursor at C(auto), then click the left mouse but- 
ton. 


Become Familiar With the Three Debugging Modes 


You should be in auto mode now, and you should see the FILE window but not 
the DISASSEMBLY window (because you’re program is in C code). Auto 
mode automatically switches between an assembly and a C display, depend- 
ing on where you are in your program. Here’s a demonstration of that: 


Run to a point in your program that executes assembly language code: 


go meminit 


You're still in auto mode, but you should now see the DISASSEMBLY window. 
The current PC should be at the statement that defines the meminit label. 


Try This: 


You can also switch modes by typing one of these commands: 


asm __ switches to assembly-only mode 
c switches to auto mode 
mix switches to mixed mode 


Switch back to mixed mode before continuing: 


mix 


rlahiway Point 


You’ve finished the first half of the tutorial and the 
first set of lessons. 


If you want to close the debugger, just type QUIT @). When you come back, 
reinvoke the debugger and load the sample program (page 2-3). Then turn 
to page 2-14 and continue with the second set of lessons. 
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Open Another Text File, Then Redisplay a C Source File / Use the Basic RUN Command 


Open another text file, then redisplay a C source file 


In addition to what you already know about the FILE window and the FILE com- 
mand, you should also know that: 


[.} You can display any text file in the FILE window. 


[_] Ifyou enter any command that requires the debugger to display a C source 
file, it automatically displays that code in the FILE window (regardless of 
whether the window is open or not and regardless of what is already dis- 
played in the FILE window). 


Display a file that isn’t a C source file: 


file ..\autoexec.bat 


This replaces sample.c in the FILE window with your autoexec. 


Remember, you can tell which file you're displaying by the label in the FILE 
window. Right now, the label should say FILE: autoexec.bat. 


Redisplay another C source file (sample.c): 


func call 


Now the FILE window label should say FILE: sample.c because the call() func- 
tion is in sample.c. 


Use the basic RUN command 


The debugger provides you with several ways of running code, but it has one 
basic run command. 


Run your entire program: 


run 


Entered this way, the command basically means “run forever’. You may not 
have that much time! 


This isn’t very exciting: halt program execution: 


ESC 


Set Some Breakpoints 


Set some breakpoints 


When you halted execution in the previous step, you should have seen 
changes in the display similar to the changes you saw when you entered go 
main earlier in the tutorial. When you pressed , you had little control over 
where the program stopped. Knowing that information changed was nice, but 
what part of the program affected the information? 


This information would be much more useful if you picked an explicit stopping 
point before running the program. Then, when the information changed, you’d 
have a better understanding of what caused the changes. You can stop pro- 
gram execution in this way by setting software breakpoints. 


Here’s an example of one of the debugger’s informative capabilities. In this ex- 
ample, you're going to benchmark some code; this means that you'll ask the 
debugger to count the number of CPU clock cycles that are consumed by a 
certain portion of code. 


| Important! | This lesson assumes that you’re displaying the contents of 
sample.c in the FILE window. If you aren’t, enter: 


file sample.c 


Benchmark some code: 


1) Scroll to line 38 in the FILE window (the meminit() statement) and set 
a breakpoint at that line: 


a) Point the mouse cursor at the statement on line 38. 


UU b) Click the left mouse button. Notice how the line is highlighted; 
this identifies a breakpointed statement. 


Set another breakpoint at line 46 ( the for (;;); statement). 
Reset the program entry point: 

restart 

Enter the run command: 


run This runs to the first breakpoint 


lesson continues on the next page > 
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Set Some Breakpoints / Watch Some Values and Single-Step Through Code 


5) Enter the runb command: 


runb This runs to the second breakpoint 


6) Nowuse the ? command to examine the contents of the CLK pseudo- 
register: 


? clk (2) 


The debugger now shows a number in the display area; this is the number of 
CPU clock cycles consumed by the portion of code between the two break- 
pointed C statements. 


| Important! | The value in the CLK pseudoregister is valid only when you 
execute the RUNB command and when that execution is halted on break- 
pointed statements. 


Delete both software breakpoints: 


br The BR (breakpoint reset) command deletes 
all breakpoints that were set 


Watch some values and single-step through code 


Now you know how to update the display without running your entire program; 
you can set breakpoints to obtain information at specific points in your pro- 
gram. But what if you want to update the display after each statement? No, you 
don't have to set a breakpoint at every statement—you can use single-step 
execution. 


Set up for the single-step example: 


restart 
go main 


The debugger has another type of window called a WATCH window that’s very 
useful in combination with single-step execution. What’s a WATCH window 
for? Suppose you are interested in only a few specific register values, not all 
of the registers shown in the CPU window. Or suppose you are interested in 
a particular memory location or in the value of some variable. You can observe 
these data items in a WATCH window. 


Watch Some Values and Single-Step Through Code 


Set up the WATCH window before you start the single-step execution. 


Open a WATCH window: 
sp 


pc, Program Counter 
*0x80981f, Call: 
i 


You may have noticed that the WA (watch add) command can have one or two 
parameters. The first parameter is the item that you’re watching. The second 
parameter is an optional label. 


Ifthe WATCH window isn’t wide enough to display the PC value, resize the win- 
dow. 


Now try out the single-step commands. Hint: Watch the PC in the FILE and 
DISASSEMBLY windows; watch the value of i in the WATCH window. 


Single-step through the sample program: 


step 50 
Observe the FILE, DISASSEMBLY, and WATCH windows. 


Try This: | Notice that the step command single-stepped each assembly lan- 
guage statement (in fact, you single-stepped through 50 assembly language 
statements). Did you also notice that the FILE window displayed the source 
for the call() function when it was called? The debugger supports more single- 
step commands that have a slightly different flavor. 


(_] For example, if you enter: 
cstep 50 
you'll single-step 50 C statements, not assembly language statements 
(notice how the PC “jumps” in the DISASSEMBLY window). 

[_} Reset the program entry point and run to main(). 


restart 
go main 


Now enter the NEXT command, as shown below. You'll be single-stepping 
50 assembly language statements, but the FILE window doesn't display 
the source for the call() function when call() is executed. 


next 50 
(There’s also a CNEXT command that “nexts” in terms of C statements.) 


An Introductory Tutorial to the C Source Debugger 2-17 


Run Code Conditionally 


Run code conditionally 


Try executing this loop one more time. Take a look at this code; it’s doing a lot 
of work with a variable named i. You may want to check the value of i at specific 
points instead of after each statement. To do this, you set software breakpoints 
at the statements you're interested in and then initiate a conditional run. 


First, clear out the WATCH window so that you won't be distracted by any su- 
perfluous data items. 


Delete the first three data items from the WATCH window (don’t watch 
them anymore). 


wd 3 
wd 2 
wd 1 


The variable i was the fourth item added to the WATCH window in the previous 
tutorial step, and it should now be the only remaining item in the window. (The 
sample program declares two variables named i: one is a global variable, and 
the other is local to main(). Because you executed code and are now in main() 
as a result of the previous step, you’re watching the i variable that’s local to 
main (). 


Set up for the conditional run examples: 
Set software breakpoints at lines 38 and 44. 


Set up for conditional run example: 


restart 


run 


Initiate the conditional run: 


run i<10 


This causes the debugger to run through the loop as long as the value of iis 
less than 10. Each time the debugger encounters the breakpoints in the loop, 
it updates the value of i in the WATCH window. 


WHATIS that? 


Run Code Conditionally / WHATIS That? 


When the conditional run completes, close the WATCH window. 


Close the WATCH window: 


wr [2] 


At some point, you might like to obtain some information about the types of 
data in your C program. Maybe things won't be working quite the way you’d 
planned, and you'll find yourself saying something like “... but isn’t that sup- 
posed to point to an integer?” Here’s how you can check on this kind of in- 
formation: be sure to watch the COMMAND window display area as you enter 
these commands. 


Use the WHATIS command to find the types of some of the variables de- 
clared in the sample program: 


whatis genum 
enum yyy genum; genum is an enumerated type 
whatis tiny6 
Struct at tiny6 is a structure 
aah: {Be 
chine 326 
alioe, S56 
aig, 7h 


aioe. ¥AG 


}} Wealianyse 


whatis call 
inte adele ())ry call is a function that returns an integer 


whatis s 


short s; s is a short unsigned integer 
whatis zzz 
Sie rUCt azz zt zzz is a very long structure 
ant bil; 
ahighe 10/217 
Press to halt long listings 
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Clear the COMMAND window display area 


After displaying all of these types, you may want to clear them away. This is 
easy to do. 


Clear the COMMAND window display area: 


cls 


Try This: | CLs isn't the only system-type command that the debugger sup- 
ports. 
cd .. Change back to the main directory 
dir Show a listing of the current directory 
ed c3xhll or cd sim3x Change back to the debugger directory 


Display the contents of an aggregate data type 
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The WATCH windowis convenient for watching single, or sca/ar, values. When 
you're debugging a C program, though, you may need to observe values that 
aren't scalar; for example, you might need to observe the effects of program 
execution on an array. The debugger provides another type of window called 
a DISP window, where you can display the individual members of an array or 
structure. 


Show a structure in a DISP window: 
disp small 


Close the DISP window: 


Show another structure in a DISP window: 


disp bigl 


Display the Contents of an Aggregate Data Type 


Now you should see a display like the one below. The newly opened DISP win- 
dow becomes the active window. Like the FILE window, you can always tell 
what’s being displayed because of the way the DISP window is labeled. Right 
now, it should say DISP: big1. 


DISP: bigl 


(Note that the values displayed in this diagram may be different from what you 
see on the screen.) 


[_.] Members b1, b2, 63, b4, and b5 are ints; you can tell because they’re dis- 
played as integers (shown as plain numbers without prefixes). 


[| Member q1 is an array; you can tell because qi shows [. . .] instead of a 
value. 


[_.} Member q2 is another structure; you can tell because q2 shows {. . .} 
instead of a value. 


[_] Member q3 is a pointer; you can tell because itis displayed as a hexadeci- 
mal address (indicated by a Ox prefix) instead of an integer value. 


If a member of a structure or an array is itself a structure or an array, or even 
a pointer, you can display its members (or the data it points to) in additional 
DISP windows (referred to as the original DISP window's children). 


Display what q3 is pointing to: 


~ 1) Point at the address displayed next to the q3 label in big1’s 
display. 


U 2) Click the left mouse button. 


This opens a second DISP window, named big1.q3, that shows what q3 is 
pointing to (it’s pointing to another structure). Close this DISP window or move 
it out of the way. 


lesson continues on the next page > 
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S Display array q1 in another DISP window: 


nx 


tt 


1) Point at the [. . .] displayed next to the q1 label in big1’s dis- 


play. 


2) Click the left mouse button. 


This opens another DISP window labeled DISP: big1.q1. 


| Important! | qi is actually a two-member array of structures. To view the two 
different structures, uSe (CONTROL) (PAGEDOWN) and (CONTROL) (PAGEUP). (Look at 
the name of this DISP window when you're switching.) 


——a Try This: 


Display structure q2 in another DISP window. 


1) Close the additional DISP windows or move them out of the way so that 
you can clearly see the original DISP window that you opened to display 


big1. 


2) Make big1’s DISP window the active window. 


®@_ 3) Use these arrow keys to move the field cursor (_) through the list of big1’s 
members until the cursor points to q2. 


4) Now press (F9). 


Close all of the DISP windows: 


1) Make big1’s DISP window the active window. 


2) Press : 


When you close the main DISP window, the debugger closes all of its children 


as well. 
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Display Data in Another Format 


Display data in another format 


Usually, when you add an item to the WATCH window or open a DISP window, 
the data is shown in its natural format. This means that ints are shown as inte- 
gers, floats are shown as floating-point values, etc. Occasionally, you may 
wish to view data in a different format. This can be especially important if you 
want to show memory or register contents in another format. 


One way to display data in another format is through casting (which is part of 
the C language). In the expression below, the *(float *) portion of the expres- 
sion tells the debugger to treat address 0x809c00 as type float (exponential 
floating-point format). 


Display memory contents in floating-point format: 


disp *(float *)0x809c00 


This opens a DISP window to show memory contents in an array format. The 
array member identifiers don’t necessarily correspond to actual addresses— 
they're relative to the first address you request with the DISP command. In this 
case, the item displayed as item [0] is the contents of address 0x0080 9c00—it 
isn’tmemory location 0. Note that youcan scroll through the memory displayed 
inthe DISP window; item [1] is at Ox0080 9c01, and item [-1] is at Ox0080 Qbff. 


You can also change display formats according to data type. This affects all 
data of a specific C data type. 


Change display formats according to data types by using the SETF (set 
format) command: 


1) Forcomparison, watch the following variables. Their C data types are 
listed on the right. 


wa i Type int 


wa f Type float 
wad Type double 


You can list all the data types and their current display formats: 


setf 


lesson continues on the next page > 
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Display Data in Another Format 


Now display the following data types with new formats: 


setf int, c Ints as characters 
setf float, o Floats as octal integers 
setf double, x Doubles as hex integers 


List the data types to display formats again; note the changes in the 
display: 


setf 


Add the variables to the WATCH window again; use labels to identify 
the additions: 


wa i, NEWi 
wa £, NEWE 
wa d, NEWd 


Notice the differences in the display formats between the first versions 
you added and these new versions. 


Now reset all data types back to their defaults: 


sett * 


A third way to display data in another format is to use the DISP, ?, MEM, or WA 
command with an optional parameter that identifies the new display format. 
The following examples are for ? and WA—DISP and MEM work similarly. 


Use display formats with the ? and WA commands: 
1) Evaluate a variable and display it as a character: 
? small.ra[1],c 


2) Add avariable to the watch window and display it as an octal integer: 


wa str.a,,o Notice that because no label was used 
with WA, an extra comma was inserted; 

otherwise, the o parameter would have 

been interpreted as a label. 
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Try This: 


Display Data in Another Format / Change Some Values 


You can also watch registers RO-R7 as floating-point values by us- 


ing the special symbols FO-F7. You might also want to display memory con- 
tents in floating-point format. For example, you can display the contents of 
location 0x809800 in floating-point format: 


disp *(float *)0x809800 


To get ready for the next step, close the DISP and WATCH windows. 


Change some values 


You can edit the values displayed in the MEMORY, CPU, WATCH, and DISP 


windows. 


S Change a value in memory: 


1) Move or close the WATCH window if it’s obscuring the 


MEMORY window; then display memory beginning with ad- 
dress 0x0080 9800: 


mem 0x809800 
Point to the contents of memory location 0x0080 9800. 


Click the left mouse button. Notice that this highlights and 
identifies the field to be edited. 


Type 00000000. 


Press to enter the new value. 


Press to conclude editing. 


lesson continues on the next page > 
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Change Some Values / Define a Memory Map 


(F9) 


2) 


ESC. 


Try This: | Here’s another method for editing data that lets you edit a few more 
values at once. 
1) Make the CPU window the active window: 
win CPU 


2) Press the arrow keys until the field cursor (_ ) points to the PC contents. 


) 
) Press 3). 
) Type 0080985d. 
5) Press @ twice. You should now be pointing at the contents of register RO. 
) 
) 
) 


OQ 


Type 0001 74f9. 
Press @) to enter the new value. 


00 


Press (ESC) to conclude editing. 


Define a memory map 
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You can set up a memory map to tell the debugger which areas of memory it 
can and can’t access. This is called memory mapping. When you invoked the 
debugger for this tutorial, the debugger automatically read a default memory 
map from the initialization batch file included in the c3xhll or sim3x directory. 
For the purposes of the sample program, that’s fine (which is why this lesson 
was saved for the end). 


View the default memory map settings: 


m1 (2 | 


Look in the COMMAND window display area—you'll see a listing of the areas 
that are currently mapped. 


It’s easy to add new ranges to the map or delete existing ranges. 


Change the memory map: 

1) Use the MD (memory delete) command to delete the block of memory: 
md 0x0 
This deletes the block of memory beginning at address 0. 


2) Usethe MA (memory add) command to define a new block of memory: 


ma 0x2000, Oxfff, RAM 


Define Your Own Command String / Close the Debugger 


Define your own command string 


If you find that you often enter a command with the same parameters, or often 
enter the same commands in sequence, you will find it helpful to have a short- 
hand method for entering these commands. The debugger provides an alias- 
ing feature that allows you to do this. 


This lesson shows you how you can define an alias to set up a memory map, 
defining the same map that was defined in the previous lesson. 


Define an alias for setting up the memory map: 


1) Usethe ALIAS commandto associate a nickname with the commands 
used for defining a memory map: 


alias mymap,”mr;ma 0x2000, Oxfff,RAM;m1” 


Now, to use this memory map, just enter the alias name: 
mymap 
This is equivalent to entering the following three commands: 


mr 
ma 0x2000,O0xfff, RAM 
ml 


Close the debugger 


This is the end of the tutorial—close the debugger. 


Close the debugger and return to the operating system: 


quit 
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Chapter 3 


The Debugger Display 


The ’C3x C source debugger has a window-oriented display. This chapter 
shows what windows can look like and describes the basic types of windows 


that you'll use. 


Topic Page 
3.1. Debugging Modes and Default Displays 3-2 
Auto mode 3-2 
Assembly mode ois) 
Mixed mode 3-4 
Restrictions associated with debugging modes 3-4 
3.2 Descriptions of the Different Kinds of Windows 3-5 
and Their Contents 
COMMAND window 3-6 
DISASSEMBLY window 3-7 
FILE window 3-8 
CALLS window ci) 
PROFILE window 3-11 
MEMORY windows 3-12 
CPU window 3-15 
DISP windows 3-16 
WATCH window 3-17 
3.3. Cursors 3-18 
3.4 The Active Window 3-19 
Identifying the active window 3-19 
Selecting the active window 3-20 
3.5 Manipulating Windows 3-21 
Resizing a window 3-21 
Zooming a window 3-23 
Moving a window 3-24 
3.6 Manipulating a Window’s Contents 3-26 
Scrolling through a window’s contents 3-26 
Editing the data displayed in windows 3-28 
3.7 Closing a Window 3-29 
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Debugging Modes and Default Displays 


3.1 Debugging Modes and Default Displays 


Auto mode 


The basic debugger environment has three debugging modes: 


[_} Auto mode 
[|_| Assembly mode 
_} Mixed mode 


Each mode changes the debugger display by adding or hiding specific win- 
dows. Some windows, such as the COMMAND window, may be present in all 
modes. The following figures show the default displays for these modes and 
show the windows that the debugger automatically displays for these modes. 


These modes cannot be used within the profiling environment; only the COM- 
MAND, PROFILE, DISASSEMBLY, and FILE windows are available. 


In auto mode, the debugger automatically displays whatever type of code is 
currently running—assembly language or C. This is the default mode; when 
you first invoke the debugger, you'll see a display similar to Figure 3—1. Auto 
mode has two types of displays: 


[_} When the debugger is running assembly language code, you'll see an as- 
sembly display similar to the one in Figure 3-1. The DISASSEMBLY win- 
dow displays the reverse assembly of memory contents. 


Figure 3—1. Typical Assembly Display (for Auto Mode and Assembly Mode) 


3-2 


Load Break Watch Memory Color MoDe Pin Run=F5 Step=F8 oaeecrngy | 
[—DISASSEMBLY: 1 CPU 1 
£00075 00£000b2 ABSI 178,DP Alec o0£00076 sp 00000755 & 
£00076 087000£0 c_intOO: LDI 240,DP RO 00000003 R1 00000005 
£00077 08340074 LDI @074H, SP R2 00000007 R3 00000000 
EOC OT CMOS OLOCTA hs Eph) R4 00000000 R5 00000000 
£00079 087000£0 LDI 240,DP R6 00000000 R7 00000000 
£0007a 08280075 LDI @075H, ARO AR) GALORE Ae GERERRE 
£0007b O4e8fffF CMPI -1,ARO 
£0007c 6a05000c BZ £00089 pe Pes or oenee 
AR4 00000000 AR5 00000000 
£0007d 08412001 LDI *ARO++ (1) ,R1 
£0007e 6a250008 BZD £00089 Fe oon Fe eee 
£0007£ 08492001 LDI *ARO++ (1) ,ARL TROEOOOOCO0CRMEELETIOCOOOO00 
£00080 08402001 LDI *ARO++ (1) ,RO ST 00000000 RC 00000000 
£00081 18610001 SUBI 1,R1 RS 00000000 RE 00000000 
£00082 139b9991 RPTS R11 V| DP 00000000 BK 00000000 ¥ 
£00083 da002120 LDI *ARO++(1),RO || sx | IE 00000000 IF 0000000 | 
‘COMMAND’ MEMORY 1 
TMS3203x, Debugger Version 4.60 000000 0000004b 00000040 00000041 00000042 A 
Copyright (c) 1989, 1993 Texas In 000004 00000043 00000044 00000045 00000046 
TMS320C3x 000008 00000047 00000048 00000049 0000004a 
Loading sample.out 00000c 00000000 00000000 00000000 00000000 
Done 000010 00000000 00000000 00000000 00000000 Ww 
>>> {il 000014 00000000 00000000 00000000 vouwons | 


Debugging Modes and Default Displays 


[_} When the debugger is running C code, you'll see a C display similar to the 
one in Figure 3-2. (This assumes that the debugger can find your C 
source file to display in the FILE window. If the debugger can’t find your 
source, then it switches to mixed mode.) 


Figure 3-2. Typical C Display (for Auto Mode Only) 


Assembly mode 


| ET Break Watch Memory Color MoDe Pin Run=F5 Step=F8 Next=F10 
FILE: sample.c 
00038 extern call(); 

00039 extern meminit (); 

00040 main() 

00041 { 

00042 register int i = 0; 
00043 int j = 0, k = 0; 
00044 

00045 meminit () ; 


00046 for (i = 0, i , 0x50000; i++) 
00047 { 

00048 call (i); 

00049 aif (4 & 1) 5 += i; 
00050 aail[k][k] = 3; 

00051 if (!(i & OxFFFF)) k++; 
00052 


‘CALLS 


COMMAND 1 
TS320C3x Debugger Version 4.60 Alois: main() 
(c) Copyright 1989, 1993 Texas Instruments Inc. 

TMS320C3x 
Loading sample.out v 
>>> i | 


When you're running assembly language code, the debugger automatically 
displays windows as described for assembly mode. 


When you’re running C code, the debugger automatically displays the 
COMMAND, CALLS, and FILE windows. If you want, you can also open a 
WATCH window and DISP windows. 


Assembly mode is for viewing assembly language programs only. In this 
mode, you'll see a display similar to the one shown in Figure 3—1. When you're 
in assembly mode, you'll always see the assembly display, regardless of 
whether C or assembly language is currently running. 


Windows that are automatically displayed in assembly mode include the 
MEMORY window, the DISASSEMBLY window, the CPU window, and the 
COMMAND window. If you want, you can also open a WATCH window in as- 
sembly mode. 
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Debugging Modes and Default Displays 


Mixed mode 


Mixed mode is for viewing assembly language and C code at the same time. 
Figure 3-3 shows the default display for mixed mode. 


Figure 3-3. Typical Mixed Display (for Mixed Mode Only) 


Load Break Watch Memory Color MoDe Pin Run=F5 Step=F8 Next=F10 
-—DISASSEMBLY- 1 CPU 1 
400000 O£f2b0000 main: PUSH AR3 4 PC 00f£00076 SP 00000755 A 
400001 080b0014 LDI SP, AR3 RO 00000003 R1 00000005 
400002 02740002 ADDI 2,SP R2 00000007 R3 00000000 
400003 0£240000 PUSH R4 R4 00000000 R5 00000000 
400004 08640000 LDI 0,R4 R6 00000000 R7 00000000 
400005 15440301 STI R4, *+AR3 (1) ARO 00001802 AR1 00000000 
400006 15440302 STI R4, *+AR3 (2) AR2 00000000 AR3 00000000 
400007 62400057 CALL meminit v AR4 00000000 AR5 00000000 v 
400008 08640000 LDI 0,R4 i AR6 00000000 AR7 ooo00c0e | 
P—FILE: sample.c ‘CALLS 


00037 extern struct zzz *func(): ry 1: main() 
00038 extern call(); 
00039 extern meminit () ; 


00040 main() 


00041 { 
00042 register int i = 0; v 

00043 ante —s0) kaa), i 

‘COMMAND MEMORY | 
Loading sample. out 000000 0000004b 00000040 00000041 00000042 


Done 000004 00000043 00000044 00000045 00000046 
EI) GE MOLG 000008 00000047 00000048 00000049 0000004a 
>> 00000c 00000000 00000000 00000000 00000000 


In mixed mode, the debugger displays all windows that can be displayed in 
auto and assembly modes—regardless of whether you’re currently running 
assembly language or C code. This is useful for finding bugs in C programs 
that exploit specific architectural features of the 'C3x. 


Restrictions associated with debugging modes 
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The assembly language code that the debugger shows you is the disassembly 
(reverse assembly) of the memory contents. If you load object code into 
memory, then the assembly language code is the disassembly of that object 
code. If you don’tload an object file, then the disassembly won’tbe very useful. 


Some commands are valid only in certain modes, especially if a command ap- 
plies to a window thatis visible only in certain modes. In this case, entering the 
command causes the debugger to switch to the mode that is appropriate for 
the command. This applies to these commands: 


dasm func mem 
calls file disp 


Descriptions of the Different Kinds of Windows and Their Contents 


3.2 Descriptions of the Different Kinds of Windows and Their Contents 


The debugger can show several types of windows. This section lists the vari- 
ous types of windows and describes their characteristics. 


The name at the top of a window identifies the window’s name. Each type of 
window serves a specific purpose and has unique characteristics. There are 
nine different windows, divided into four general categories: 


[_} The COMMAND window provides an area for typing in commands and 
for displaying various types of information such as progress messages, 
error messages, or command output. 


[_} Code-display windows are for displaying assembly language or C code. 
There are three code-display windows: 


HM TheDISASSEMBLY window displays the disassembly (assembly lan- 
guage version) of memory contents. 


M@ The FILE window displays any text file that you want to display; its 
main purpose, however, is to display C source code. 


HM The CALLS window identifies the current function traceback (when C 
code is running). 


[_.] The PROFILE window displays statistics about code execution. This win- 
dow is available only when you are in the profiling environment. 


[|_| Data-display windows are for observing and modifying various types of 
data. There are four data-display windows: 


@ AMEMORY window displays the contents of a range of memory. You 
can display up to four MEMORY windows at one time. 


HM The CPU window displays the contents of ’C3x registers. 


@ ADISP window displays the contents of an aggregate type such as an 
array or structure, showing the values of the individual members. You 
can display up to 120 DISP windows at one time. 


HM The WATCH window displays selected data such as variables, specif- 
ic registers, or memory locations. 


You can move or resize any of these windows; you can also edit any value in 
a data-display window. Before you can perform any of these actions, however, 
you must select the window you want to move, resize, or edit and make it the 
active window. For more information about making a window active, see Sec- 
tion 3.4, The Active Window, on page 3-19. 


The remainder of this section describes the individual windows. 
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COMMAND window 
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display 
area 


line 


COMMAND 
IS3203x, Debugger Version 4.60 


Copyright (c) 1989, 1993 Texas Instruments Inc 
Loading sample.out 
Done 


ile sample.c 


p- 


command____£_,,, go. main == 
command line 


cursor 


y 


Purpose 


Editable? 
Modes 
Created 
Affected by 


Command line is editable; command output isn’t 


All modes 


Automatically 


[.} Any input that creates an error 


The COMMAND window has two parts: 


|_| Provides an area for entering commands 


[_] All commands entered on the command line 
[_] All commands that display output in the display area 


[_.] Provides an area for echoing commands and displaying 
command output, errors, and messages 


[_} Command line. This is where you enter commands. When you want to 
enter a command, just type—no matter which window is active. The de- 
bugger keeps a list of the last 50 commands that you entered. You can se- 
lect and re-enter commands from the list without retyping them. (For more 
information on using the command history, see Using the command histo- 
ry, page 4-5.) 


(_] Display area. This area of the COMMAND window echoes the command 
that you entered, shows any output from the command, and displays de- 
bugger messages. 


For more information about the COMMAND window and entering commands, 
refer to Chapter4 , Entering and Using Commands. 


Descriptions of the Different Kinds of Windows and Their Contents 


DISASSEMBLY window 
; disassembly 
memory object (assembly language 
address code constructed from object code) 
-—DISASSEMBLY 
400063 0040009£ *+ARO (159) ,RO 
400064 087000040 c_int0O0: LDI 64,DP current PC 
400065 08340062 LDI @062H, SP 
400066 080b0014 LDI SP,AR3 
400067 08700040 LDI 64,DP 
400068 08280063 LDI @063H, ARO 
400069 O4e8ffff CMPI -1,AR0 
40006a 6a05000c BZ 400077 
40006b 08412001 LDI *ARO++(1),R1 
Purpose Displays the disassembly (or reverse assembly) of memory 
contents 
Editable? No; pressing the edit key (€9)) or the left mouse button sets 
a software breakpoint on an assembly language statement 
Modes Auto (assembly display only), assembly, and mixed 
Created Automatically 


Affected by [_.}| DASM and ADDR commands 
[} Breakpoint and run commands 


Within the DISASSEMBLY window, the debugger highlights 


[_] The statement thatthe PC is pointing to (if that line is in the current display) 

[.] Any statements with software breakpoints 

[] The address and object code fields for all statements associated with the 
current C statement, as shown below 


“ DISASSEMBLY- ” 
400000 O£2b0000 main: PUSH AR3 
400001 080b0014 
ae 400002 02740002 
These assembly 400003 0£240000 
language statements 400004 08640000 LDI 
are associated with rte: t1.c 
this C statement | 00038 extern call(); 


00039 exterm meminit (); 
main () 


00041 { 


p> 


current PC 
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FILE window 


-—FILE: sample.c 1 
00001 vetruct xxx Se{ ant a,b ic; ant tle 2p int fae struct. tx: 


00002 str, astr[10], aastr[ 
text | vat enter aae int Wl a2) usu) 5 6] struct six ue; 6} 
Ex 00004 struct zzz { int bl1,b2,be,b4,b5; struct xxx ql[2],q2; str 


file 


00005 bigl, *big2, big3[6]; 
00006 struct {wants v7, 2,7  inceosptr-a float. *fptr;ichar ra|[/5 Vv 
00007 enum yyy { RED, GREEN, BLUE } genum, *penum, aenum[5] [4] | 


Purpose Shows any text file you want to display 


Editable? No; if the FILE window displays C code, pressing the edit key 
(C3) ) or the left mouse button sets a software breakpoint on 
aC statement 


Modes Auto (C display only) and mixed 


Created [__} With FILE command 
Automatically when you’re in auto or mixed mode and 
your program begins executing C code 


L} 
Affected by [| FILE, FUNC, and ADDR commands 
_} Breakpoint and run commands 


You can use the FILE command to display the contents of any file within the 
FILE window, but this window is especially useful for viewing C source files. 
Whenever you single-step a program or run a program and halt execution, the 
FILE window automatically displays the C source associated with the current 
point in your program. This overwrites any other file that may have been dis- 
played in the window. 


Within the FILE window, the debugger highlights: 


[_] The statementthatthe PC is pointing to (if that line is in the current display) 
[.} Any statements where you’ve set a software breakpoint 


CALLS window 


Descriptions of the Different Kinds of Windows and Their Contents 


--CALLS 
order of functions called ~~. eee 

PAS Kop Ulal (iy) 
abe in() 


names of functions called 


current function 
is at top of list 


Lists the function you're in, its caller, and the caller’s caller, 


No; pressing the edit key ()) or the left mouse button 


changes the FILE display to show the source associated with 


[__| With the CALLS command if you closed the window 


Purpose 

etc., as long as each function is a C function 
Editable? 

the called function 
Modes Auto (C display only) and mixed 
Created [_} Automatically when you're displaying C code 
Affected by Run and single-step commands 


The display in the CALLS window changes automatically to reflect the latest 


function call. 


@ 


If you haven’t run any code, then no func- 
tions have been called yet. You'll also see 
this if you’re running an assembly func- 
tion not written in C code. 


In C programs, the first C function is main. 


As your program runs, the contents of 
the CALLS window change to reflect 
the current routine that you’re in and 

where the routine was called from. 
When you exit a routine, its name is 
popped from the CALLS list. 


~ 


—CALLS 
1: **UNKNOWN 


CALLS 


22) xcald() 


1: main() 
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If a function name is listed in the CALLS window, you can easily display the 
function in the FILE window: 


1) Point the mouse cursor at the appropriate function name that is listed in 
the CALLS window. 


2) Click the left mouse button. This displays the selected function in the FILE 
window. 


1) Make the CALLS window the active window (see Section 3.4, The Active 
Window, page 3-19). 


2) Use the arrow keys to move up/down through the list of function names 
until the appropriate function is indicated. 


3) Press (3). This displays the selected function in the FILE window. 


You can close and reopen the CALLS window. 


[_] Closing the window is a two-step process: 
1) Make the CALLS window the active window. 
2) Press (4). 


[_} Toreopenthe CALLS window after you've closed it, enter the CALLS com- 
mand. The format for this command is: 


calls 


Descriptions of the Different Kinds of Windows and Their Contents 


PROFILE window 
profile data 
PROFILE 
Area Name Count Inclusive Incl-Max Exclusive Excl-Max 4 
AR 00£00001-00£00008 1 65 65 19 19 
profile CL <sample>#58 1 50 50 7 Yu 
areas CR <sample>#59-64 ak 87 87 44 44 
CF call() 24 1623 99 1089 ‘SSI 
AL meminit 1 3 3 3 3 V 
AL 00£00059 disabled | 
Purpose Displays statistics collected during a profiling session 
Editable? No 
Modes Auto 
Created By invoking the debugger with the —profile option 


Affected by [| The PF and PQ commands 
[_.} Any commands on the View menu 
[_] Clicking in the header area of the window 


The PROFILE window is visible only when you are in the profiling environment. 
The illustration above shows the window with a default set of data, but the dis- 
play can be modified to show specific sets of data collected during a profiling 
session. 


Note that within the profiling environment, the only other available windows are 
the COMMAND window, the DISASSEMBLY window, and the FILE window. 


For more information about the PROFILE window (and about profiling in gen- 
eral), refer to Chapter 10, Profiling Code Execution. 
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MEMORY windows 


-— MEMORY 


000000 00000000 00000001 00000002 00000003 


00004 00000004 00000005 00000006 000000 

000008 00000008 00000009 0000000a 0000000b 
addresses data 

00000c 0000000c 0000000d 0 £ 

00010 00000010 00000001100000012 00000013 


000014 00000014 00000015 00000016 00000017 


Purpose Displays the contents of memory 
Editable? Yes—you can edit the data (but not the addresses) 
Modes Auto (assembly display only), assembly, and mixed 


Created [_]} Automatically (the default MEMORY window only) 


[__} With the MEM# commands (up to three additional 
MEMORY windows) 


Affected by MEM commands: MEM, MEM1, MEM2, and MEM3 


A MEMORY window has two parts: 


(_] Addresses. The first column of numbers identifies the addresses of the 
first column of displayed data. No matter how many columns of data you 
display, only one address column is displayed. Each address in this col- 
umn identifies the address of the data immediately to its right. 


(_} Data. The remaining columns display the values at the listed addresses. 
You can display more data by making the window wider and/or longer. 


The MEMORY window above has four columns of data, so each new ad- 
dress is incremented by four. Although the window shows four columns of 
data, there is still only one column of addresses; the first value is at ad- 
dress 0x000000, the second at address 0x000001, etc.; the fifth value 
(first value in the second row) is at address 0x000004, the sixth at address 
0x000005, etc. 


As you run programs, some memory values change as the result of program 
execution. The debugger highlights the changed values. Depending on how 
you configure memory for your application, some locations may be invalid/un- 
configured. The debugger also highlights these locations (by default, it shows 
these locations in red). 


Descriptions of the Different Kinds of Windows and Their Contents 


Three additional MEMORY windows called MEMORY1, MEMORY2, and 
MEMORY? are available. The default MEMORY window does not have an ex- 
tension number in its name; this is because MEMORY1, MEMORY2, and 
MEMORY%3 are optional windows and can be opened and closed throughout 
your debugging session. Having four windows allows you to view four different 
memory ranges. Refer to Figure 3-4. 


Figure 3—4. The Default and Additional MEMORY Windows 


(MEMORY 3 


000060 00000000 00000000 00000000 ooo00000 4 MeGGEy a 
007 MEMORY 2 winagow 
00| 900058 0820005b 10150000 78000000 00002000 


00) 00007— weMoRY1* 
00} 0000 


mannan 


000050 0820005b 10150000 78000000 0223005d 


00} 0000 
faite 000 MEMORY 
ood 


0000) 000000 00000000 00000001 00000002 00000003 
ou 000004 00000004 00000005 00000006 00000007 
oe 000008 00000008 00000009 0000000a 0000000b 
eed 00000c 0000000c 0000000d 0000000e o000000£ 
000010 00000010 00000001100000012 00000013 


Additional 000014 00000014 00000015 00000016 00000017 
MEMORY windows 


To create an additional MEMORY window or to display another range of 
memory in the current window, use the MEM command. 


_} Creating a new MEMORY window. 


If the default MEMORY window is the only MEMORY window open and 
you want to open another MEMORY window, enter the MEM command 
with the appropriate extension number: 


mem[#] address 


For example, if you want to create a new memory window starting at ad- 
dress 0x8000, you would enter: 


meml 0x8000 


This displays a new window, MEMORY1, showing the contents of memory 
starting at address 0x8000. 
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(_] Displaying a new memory range in the current MEMORY window. 


Displaying another block of memory identifies a new starting address for 
the memory range shown in the current MEMORY window. The debugger 
displays the contents of memory at address in the first data position in your 
MEMORY window. The end of the range is defined by the size of the win- 
dow. 


If the only memory window open is the default MEMORY window, you can 
view different memory locations by entering: 


mem_ address 


To view different memory locations in the optional MEMORY windows, use 
the MEM command with the appropriate extension number on the end. For 


example: 
To do this. . . Enter this. . . 
View the block of memory starting at address mem1 0x8000 


0x0000 8000 in the MEMORY1 window 


View another block of memory starting ataddress mem2 0x002f 
0x0000 002f in the MEMORY2 window 


EARS, | 
Note: 


If you want to view a different block of memory explicitly in the default 
MEMORY window, you can use the alias command MEMO. This works ex- 
actly the same as the MEM command. To use this command, enter: 


mem0 address 


You can close and reopen additional MEMORY windows as often as you like. 


(_} Closing an additional MEMORY window. 
Closing a window is a two-step process: 


1) Make the appropriate MEMORY window the active window (see Sec- 
tion 3.4, on page 3-19). 


2) Press (4). 


Remember, you cannot close the default MEMORY window. 


(_} Reopening an additional MEMORY window. 


To reopen an additional MEMORY window after you’ve closed it, enter the 
MEM command with its appropriate extension number. 


CPU window 
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‘CPU 


00000007 


R6 00000000 
ARO 00001802 
AR2 00000000 
AR4 00000000 


contents 


The display 
changes when you 
resize the window 


PC 00£00076 sp 00000755 & 
00000003 R1 00000005 
R3 00000000 
R5 00000000 
77 00000000 
AR1 00000000 
AR3 00009000 
000000 
AR7 00000000 
IR1 00000000 
RC 00000000 
RE 00000000 
DP 00000000 BK 00000000 V 
IE 00000000 IF 00000000 


CPU 


PC 


00£00076 
00000005 
00000000 
00000000 


RO 00000003 
R3 00000000 
R6 00000000 
AR1 00000000 


SP 00000755 
R2 00000007 
R5 00000000 
ARO 00001802 


Purpose 
Editable? 
Modes 
Created 
Affected by 


Automatically 


Displays the contents of the ’C3x registers 
Yes—you can edit the value of any displayed register 


Auto (assembly display only), assembly, and mixed 


Data-management commands 


As you run programs, some values displayed in the CPU window change as 
the result of program execution. The debugger highlights the changed values. 
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DISP windows 


--DISP: str -——__________—__, 


a 84 A 
b 86 
structure ~~ 4172 
members a DISP: str.£4 ———____, 
£27 7 [0] 44276127 A 
v [1] 1778712578 
£3  0x18740001 
member FA fleaat | [2] 555492660 


values [3] 356713217 
ae 138412802 
[5] 182452229 
[6] 35659888 
This member is an array, and [7] 37749506 
you can display its contents in [8] 134742016 \ 
a second DISP window [9] 138412801 _| 


Purpose Displays the members of a selected structure, array, or point- 
er, and the value of each member 

Editable? Yes—you can edit individual values 

Modes Auto (C display only) and mixed 

Created With the DISP command 


Affected by The DISP command 


A DISP window is similar to a WATCH window, but it shows the values of an 
entire array or structure instead of a single value. Use the DISP command to 
open a DISP window; the basic syntax is: 


disp expression 


By default, data is displayed in its natural format: 


[_] Integer values are displayed in decimal. 

[_] Floating-point values are displayed in floating-point format. 

[_] Pointers are displayed as hexadecimal addresses (with a Ox prefix). 
__.] Enumerated types are displayed symbolically. 


If any of the displayed members are arrays, structures, or pointers, you can 
bring up additional DISP windows to display their contents—up to 120 DISP 
windows can be open at once. 


WATCH window 
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WATCH 5: 
watch index—_—______"_[_1:__ aro.-——« 0 x00001802 1 
PAs X+X 4 


v 
Bg vi ss | 


label current value 
Purpose Displays the values of selected expressions 
Editable? Yes—you can edit the value of any expression whose value 


corresponds to a single storage location (in registers or 
memory). In the window above, for example, you could edit 
the value of PC but couldn’t edit the value of X+X. 


Modes Auto, assembly, and mixed 
Created With the WA command 
Affected by WA, WD, and WR commands 


The WATCH window helps you to track the values of arbitrary expressions, 
variables, and registers. Use the WA command for this; the syntax is: 


wa_ expression |, label] 


WA adds expression to the WATCH window. (If there’s no WATCH window, 
then WA also opens a WATCH window). 


To delete individual entries from the WATCH window, use the WD command. 
To delete all entires at once and close the WATCH window, use the WR com- 
mand. 


Although the CPU window displays register contents, you may not be inter- 
ested inthe values of all these registers. In this situation, it is convenient to use 
the WATCH window to track the values of the specific registers you're inter- 
ested in. 
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3.3 Cursors 
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The debugger display has three types of cursors: 


[_] The command-line cursor is a block-shaped cursor that identifies the 
current character position on the command line. Arrow keys do not affect 
the position of this cursor. 


a COMMAND: 
TMS3203x 


Done 


Simulator Version 2.01 


Loading sample.out 


file sample.c 


ep 


Lz 


>>> go ae 
command line cursor 


(_} The mouse cursor is a block-shaped cursor that tracks mouse move- 
ments over the entire display. This cursor is controlled by the mouse driver 
installed on your system; if you haven’t installed a mouse, you won’t see 


a mouse cursor on the debugger display. 


(_] The current-field cursor identifies the current field in the active window. 
On PCs, this is the hardware cursor that is associated with your graphics 
card. Arrow keys do affect this cursor’s movement. 


“ 


PG 


‘CPU 


00£00076 SP 00000755 
00000005 R2 00000007 
00000000 R5 00000000 
00000000 ARO 00001802 


00000003 
00000000 
00000000 
00000000 


= current field cursor 


p- 


The Active Window 


3.4 The Active Window 


The windows in the debugger display aren’t fixed in their position or in their 
size. You can resize them, move them around, and, in some cases, close 
them. The window that you’re going to move, resize, or close must be active. 


You can move, resize, zoom, or close only one window at a time; thus, only one 
window at atime can be the active window. Whether or not a window is active 
doesn’t affect the debugger’s ability to update information in a window—it af- 
fects only your ability to manipulate a window. 


Identifying the active window 


The debugger highlights the active window. When windows overlap on your 
display, the debugger pops the active window to be on top of other windows. 


You can alter the active window’s border style and colors if you wish; 


Figure 3-5 illustrates the default appearance of an active window and an inac- 
tive window. 


Figure 3-5. Default Appearance of an Active and an Inactive Window 


An active window (default appearance) 


‘COMMAND 
TMS320C3x Debugger Version 4.60 


Copyright (a) 1989, 1993 Texas Instrument 
TMS320C3x 
This window is high- Simulator Version 2.01 
lighted to show that it ||-t0ading sample. out 
is active ||>>> {jj 


An inactive window (default appearance) 
‘COMMAND 

Loading sample.out 
36 Symbols loaded 
Done 


This window is not file sample.c 
highlighted and is |_go main ’ 


not active |>>4j _| 


— 


a 


Note: Onmonochrome monitors, the border and selection corner are highlighted as shown in 
the illustration. On color monitors, the border and selection corner are highlighted as 
shown in the illustration, but they also change color (by default, they change from white to 
yellow when the window becomes active). 
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Selecting the active window 


" 
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a 


win 


You can use one of several methods for selecting the active window. 


1) Pointto any location within the boundaries or on any border of the desired 
window. 


2) Click the left mouse button. 


Note that if you point within the window, you might also select the current field. 
For example, 


_] Ifyou point inside the CPU window, then the register you're pointing at be- 
comes active, and the debugger treats any text that you type as anew reg- 
ister value. If you point inside the MEMORY window, then the address val- 
ue you're pointing at becomes active, and the debugger treats any text that 
you type as anew memory value. 


Press to get out of this. 


_] If you point inside the DISASSEMBLY or FILE window, you'll set a break- 
point on the statement you’re pointing to. 


Press the button again to clear the breakpoint. 


This key cycles through the windows on your display, making each one active 
in turn and making the previously active window inactive. Pressing this key 
highlights one of the windows, showing you that the window is active. Pressing 
again makes a different window active. Press as many times as nec- 
essary until the desired window becomes the active window. 


The WIN command allows you to select the active window by name. The for- 
mat of this command is 


win WINDOW NAME 


Note that the WINDOW NAME is in uppercase (matching the name exactly as 
displayed). You can spell out the entire window name, but you really need to 
specify only enough letters to identify the window. 


or 


The Active Window / Manipulating Windows 


For example, to select the DISASSEMBLY window as the active window, you 
can enter either of these two commands: 


win DISASSEMBLY 
win DISA(®) 


If several windows of the same type are visible on the screen, don’t use the 
WIN command to select one of them. 


If you supply an ambiguous name (such as C, which could stand for CPU or 
CALLS), the debugger selects the first window it finds whose name matches 
the name you supplied. If the debugger doesn’t find the window you asked for 
(because you closed the window or misspelled the name), then the WIN com- 
mand has no effect. 


3.5 Manipulating Windows 


Resizing a window 


A window's size and its position in the debugger display aren’t fixed—you can 
resize and move windows. 


Note: 


You can resize or move any window, but first the window must be active. For 
information about selecting the active window, refer to Section 3.4 (page 
3-19). 


eee sss) 


The minimum window size is three lines by four characters. The maximum win- 
dow size varies, depending on which screen size you're using, but you can’t 
make a window larger than the screen. 


There are two basic ways to resize a window: 


[_} By using the mouse 
(_] By using the SIZE command 
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U0 


size 
<“ 


3-22 


1) Point to the lower right corner of the window. This corner is highlighted— 
here’s what it looks like. 


‘COMMAND 
TMS3203x Debugger Version 4.60 


(Copyright (c) 1989, 1993 Texas Instru 
TMS320C3x 


Loading sample.out 


Bone lower right corner 


>>> eae (highlighted) 


2) Grab the highlighted corner by pressing one of the mouse buttons; while 
pressing the button, move the mouse in any direction. This resizes the win- 
dow. 


3) Release the mouse button when the window reaches the desired size. 


The SIZE command allows you to size the active window. The format of this 
command is: 


size [width, length] 
You can use the SIZE command in one of two ways: 
Method 1 Supply a specific width and length. 


Method 2 Omit the width and length parameters and use arrow keys to 
interactively resize the window. 


SIZE, method 1: Use the width and length parameters. Valid values for the 
width and length depend on the screen size and the window position on the 
screen. If the window is in the upper left corner of the screen, the maximum 
size of the window is the same as the screen size minus one line. (The extra 
line is needed for the menu bar.) For example, if the screen size is 80 charac- 
ters by 25 lines, the largest window size is 80 characters by 24 lines. 


If a window is in the middle of the display, you can’t size it to the maximum 
height and width—you can size it only to the right and bottom screen borders. 
The easiest way to make a window as large as possible is to zoom it, as de- 
scribed on page 3-23. 


For example, If you want to use commands to make the CALLS window 8 char- 
acters wide by 20 lines long, you could enter: 


win CALLS 
size 8, 20 


Zooming a window 


H 


Manipulating Windows 


SIZE, method 2: Use arrow keys to interactively resize the window. If you 
enter the SIZE command without width and /ength parameters, you can use 
arrow keys to size the window. 


© Makes the active window one line longer. 

an) Makes the active window one line shorter. 

Makes the active window one character narrower. 
Makes the active window one character wider. 


When you’re finished using the cursor keys, you must press or(#). 


For example, if you want to make the CPU window three lines longer and two 
characters narrower, you can enter: 
win CPU 


size 
@ @ @& J) |} ESC 


Another way to resize the active window is to zoom it. Zooming a window 
makes it as large as possible so that it takes up the entire display (except for 
the menu bar) and hides all the other windows. Unlike the SIZE command, 
zooming is not affected by the window’s position in the display. 


To “unzoom” a window, repeat the same steps you used to zoom it. This will 
return the window to its prezoom size and position. 


There are two basic ways to zoom or unzoom a window: 


[__} By using the mouse 
|_| By using the ZOOM command 


1) Point to the upper left corner of the window. This corner is highlighted— 
here’s what it looks like: 


‘COMMAND 
TMS3203x Debugger Version 4.60 
re (Copyright (c) 1989, 1993 Texas Instru 
TMS320C3x 
upper left corner Loading sample.out 


(highlighted) — 
>>> B 


2) Click the left mouse button. 
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Al 


(0 


move 


You can also use the ZOOM command to zoom/unzoom the window. The for- 
mat for this command is: 


zoom 


The windows in the debugger display don’t have fixed positions—you can 
move them around. 


There are two ways to move a window: 


[__] By using the mouse 
[__] By using the MOVE command 


1) Point to the left or top edge of the window. 


‘COMMAND 
TMS3203x Debugger Version 4.60 


COpyright (a) 1989, 1993 Texas Instru 
TMS320C3x 


Point to the top edge 
or the left edge 


Loading sample.out 


Done 


>>> a 


2) Press the left mouse button, but don’t release it; now move the mouse in 
any direction. 


3) Release the mouse button when the window is in the desired position. 


The MOVE command allows you to move the active window. The format of this 
command is: 


move _ [X position, Y position [, width, length ] | 
You can use the MOVE command in one of two ways: 
Method 1 Supply a specific X position and Y position. 


Method 2 Omit the X position and Y position parameters and use arrow 
keys to interactively resize the window. 


Manipulating Windows 


MOVE, method 1: Use the X position and Y position parameters. You can 
move a window by defining a new XY position for the window's upper left cor- 
ner. Valid X and Y positions depend on the screen size and the window size. 
X positions are valid if the X position plus the window width in characters is less 
than or equal to the screen width in characters. Y positions are valid if the Y 
position plus the widow height is less than or equal to the screen heightin lines. 


For example, if the window is 10 characters wide and 5 lines high and the 
screen size is 80 x 25, the command move 70, 20 would put the lower right- 
hand corner of the window in the lower right-hand corner of the screen. No X 
value greater than 70 or Y value greater than 20 would be valid in this example. 


——— ———  — SS  — — — 00 SS OO ——.WhO8=a 
Note: 


If you choose, you can resize a window at the same time you move it. To do 
this, use the width and length parameters in the same way that they are used 


for the SIZE command. 
ee | 


MOVE, method 2: Use arrow keys to interactively move the window. If you 
enter the MOVE command without X position and Y position parameters, you 
can use arrow keys to move the window: 


Moves the active window down one line. 

Moves the active window up one line. 

Moves the active window left one character position. 
Moves the active window right one character position. 


When you’re finished using the cursor keys, you must press or(2). 


For example, if you want to move the COMMAND window up two lines and 
right five characters, you can enter: 


UOBE 


win COM 
move 
MH @ GO) SS) SoS) YS & (ESC) 
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3.6 Manipulating a Window’s Contents 


Although you may be concerned with changing the way windows appear in the 
display—where they are and how big/small they are—you’ll usually be inter- 
ested in something much more important: what's in the windows. Some win- 
dows contain more information than can be displayed ona screen; others con- 
tain information that you'd like to change. This section tells you how to view 
the hidden portions of data within a window and which data can be edited. 


EE 
Note: 


You can scroll and edit only the active window. For information about select- 
ing the active window, refer to Section 3.4 (page 3-19). 


Scrolling through a window’s contents 


If you resize a window to make it smaller, you may hide information. Some- 
times, a window may contain more information than can be displayed on a 
screen. In these cases, the debugger allows you to scroll information up and 
down within the window. 


There are two ways to view hidden portions of a window’s contents: 


[_] You can use the mouse to scroll the contents of the window. 


[.} You can use function keys and arrow keys. 


SS You can use the mouse to point to the scroll arrows on the righthand side of 
the active window. This is what the scroll arrows look like: 
FILE: sample.c > 
00038 extern call(); 
00039 extern meminit (); Soe ll 
00040 main() scro up 
00041 { 
00042 register int i = 0; 
00043 anterje=s0 ka =a0; 
00044 
00045 meminit () ; 
00046 for (i = 0, i , 0x50000; i++) 
00047 { 
00048 call (i); 
00049 eve (GL 6 Sh) Ss} sea Shp 
00050 aai[k][k] = j; ee scroll Pe 
00051 if (!(i & OxFFFF)) k++; 
00052 
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To scroll window contents up or down: 


~ 1) Point to the appropriate scroll arrow. 

i 2) Press the left mouse button; continue to press it until the information you’re 

interested in is displayed within the window. 

U0 3) Release the mouse button when you’re finished scrolling. 

You can scroll up/down one line at a time by pressing the mouse button and 
releasing it immediately. 

In addition to scrolling, the debugger supports the following methods for mov- 
ing through a window's contents. 

The page-up key scrolls up through the window contents, one window length 
at atime. You can use (CONTROL) (PAGE UP) to scroll up through an array of struc- 
tures displayed in a DISP window. 

The page-down key scrolls down through the window contents, one window 
length at a time. You can use (CONTROL) (PAGEDOWN)to scroll down through an 
array of structures displayed in a DISP window. 

When the FILE window is active, pressing adjusts the window's con- 
tents so that the first line of the text file is at the top of the window. You can’t 
use outside of the FILE window. 

END When the FILE window is active, pressing adjusts the window’s contents 
so that the last line of the file is at the bottom of the window. You can’t use 
outside of the FILE window. 

a) Pressing this key moves the field cursor up one line at a time. 

© Pressing this key moves the field cursor down one line at a time. 

In the FILE window, pressing this key scrolls the display left eight characters 
at atime. In other windows, moves the field cursor left one field; at the first field 
on a line, wraps back to the last fully displayed field on the previous line. 

In the FILE window, pressing this key scrolls the display right eight characters 


at a time. In other windows, moves the field cursor right one field; at the last 
field on a line, wraps around to the first field on the next line. 
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Editing the data displayed in windows 
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You can edit the data displayed in the MEMORY, CPU, DISP, and WATCH win- 
dows by using an overwrite “click and type” method or by using commands that 
change the values. (This is described in detail in Section 7.3, Basic Methods 
for Changing Data Values, page 7-4.) 


Note: 


In the following windows, the “click and type” method of selecting data for edit- 
ing—pointing at a line and pressing or the left mouse button—does not 
allow you to modify data. 


J Inthe FILE and DISASSEMBLY windows, pressing or the mouse but- 
ton sets or clears a breakpoint on any line of code that you select. You can’t 
modify text in a FILE or DISASSEMBLY window. 


[_] Inthe CALLS window, pressing or the mouse button shows the source 
for the function named on the selected line. 


[_] Inthe PROFILE window, pressing has no effect. Clicking the mouse 
button in the header displays a different set of data; clicking the mouse but- 
ton on an area name shows the code associated with the area. 


Closing a Window 


3.7 Closing a Window 


The debugger opens various windows on the display according to the debug- 
ging mode you select. When you switch modes, the debugger may close some 
windows and open others. Additionally, you may choose to open DISP and 
WATCH windows and additional MEMORY windows. 


Most of the windows remain open—you can’t close them. However, you can 
close the CALLS, DISP, WATCH, and additional MEMORY windows. To close 
one of these windows: 


1) Make the appropriate window active. 


2) Press ; 


aa [ 
Note: 


You cannot close the default MEMORY window. 


You can also close the WATCH window by using the WR command: 
wr 


When you close a window, the debugger remembers the window’s size and 
position. The next time you open the window, it will have the same size and 
position. That is, if you close the CALLS window, then reopen it, it will have the 
same size and position as it did before you closed it. Since you can open nu- 
merous DISP and MEMORY windows, when you open one, it will occupy the 
same position as the last one of that type that you closed. 
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Chapter 4 


Entering and Using Commands 


The debugger provides you with several methods for entering commands: 


[_] From the command line 

[_.} From the pulldown menus (using keyboard combinations or the mouse) 
[__] With function keys 

[_] From a batch file 


Mouse use and function key use differ from situation to situation and are de- 
scribed throughout this book whenever applicable. This chapter includes spe- 
cific rules that apply to entering commands and using pulldown menus. Also 
included is information about entering DOS commands and defining your own 
command strings. 


Some restrictions apply to command entry for VAX and Sun versions of the 
simulator. For descriptions of these restrictions, refer to the installation guide. 
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4.1. Entering Commands From the Command Line 


The debugger supports a complete set of commands that help you to control 
and monitor program execution, customize the display, and perform other 
tasks. These commands are discussed in the various sections throughout this 
book, as they apply to the current topic. Chapter 11 summarizes all of the de- 
bugger commands with an alphabetic reference. 


Although there are a variety of methods for entering most of the commands, 
all of the commands can be entered by typing them on the command line in 
the COMMAND window. Figure 4—1 shows the COMMAND window. 


Figure 4—1. The COMMAND Window 
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COMMAND 


p- 


display 


Copyright (c) 1989, 1993, Texas Instruments Incorporated 


area Loading sample.out 

Done 

ile sample.c v 
command o main | 
line 


The COMMAND window serves two purposes. 


[_] The command line portion of the window provides you with an area for 
entering commands. For example, the command line in Figure 4—1 shows 
that a GO command was typed in (but not yet entered). 


_] The display area provides the debugger with a space for echoing com- 
mands, displaying command output, or displaying errors and messages 
for you to read. For example, the command output in Figure 4-1 shows 
the messages that are displayed when you first bring up the debugger and 
also shows that a FILE command was entered. 


If you enter acommand through an alternate method (using the mouse, a 
pulldown menu, or function keys), the COMMAND window doesn’t echo 
the entered command. 
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How to type in and enter commands 


You can type a command at almost any time; the debugger automatically 
places the text on the command line when you type. When you want to enter 
a command, just type—no matter which window is active. You don’t have to 
worry about making the COMMAND window active or moving the field cursor 
to the command line. When you start to type, the debugger usually assumes 
that you're typing a command and puts the text on the command line (except 
under certain circumstances, which are explained on the next page). Com- 
mands themselves are not case sensitive, allhough some parameters (such 
as window names) are. 


To execute a command that you’ve typed, just press @). The debugger then: 


1) Echoes the command to the display area, 
2) Executes the command and displays any resulting output, and 
3) Clears the command line when command execution completes. 


Once you’ve typed a command, you can edit the text on the command line with 
these keystrokes. 


To... Press... 
Move back over text without erasing characters (CONTROL ) or 
BACK SPACE 


Move forward through text without erasing characters (CONTROL) 
Move back over text while erasing characters DELETE ) 


Move forward through text while erasing characters (SPACE) 


Insert text into the characters that are already on the INSERT) 
command line 


Note: 
[.} You cannot use the arrow keys to move through or edit text on the com- 
mand line. 


[| Typing acommand doesn’t make the COMMAND window the active win- 
dow. 


[__] If you press @) when the cursor is in the middle of text, the debugger trun- 
cates the input text at the point where you press @). 
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Sometimes, you can’t type a command 
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At most times, you can press any alphanumeric or punctuation key on your 
keyboard (any printable character); the debugger interprets this as part of a 
command and displays the character on the commandline. Ina few instances, 
however, pressing an alphanumeric key is not interpreted as information for 
the command line. 


LJ 


When you’re pressing the key, typing certain letters causes the de- 
bugger to display a pulldown menu. 


When a pulldown menu is displayed, typing a letter causes the debugger 
to execute a selection from the menu. 


When you’re pressing the key, pressing or moves the 
command-line cursor backward or forward through the text on the com- 
mand line. 


When you're editing a field, typing enters a new value in the field. 


When you're using the MOVE or SIZE command interactively, pressing 
keys affects the size or position of the active window. Before you can enter 
any more commands, you must press to terminate the interactive 
moving or sizing. 


When you've brought up a dialog box, typing enters a parameter value at 
the current field in the box. Refer to Section 4.3 on page 4-11 for more in- 
formation on dialog boxes. 
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Using the command history 


The debugger keeps an internal list, or command history, of the commands 
that you enter. It remembers the last 50 commands that you entered. If you 
want to re-enter a command, you can move through this list, select acommand 
that you've already executed, and re-execute it. 


Use these keystrokes to move through the command history. 


To... Press... 
Repeat the last command that you entered 


Move forward through the list of executed commands, one by one 


Move backward through the list of executed commands, one by one 


As you move through the command history, the debugger displays the com- 
mands, one by one, on the command line. When you see a command that you 
want to execute, simply press @) to execute the command. You can also edit 
these displayed commands in the same manner that you can edit new com- 
mands. 


Clearing the display area 


<a 


Occasionally, you may want to completely blank out the display area of the 
COMMAND window; the debugger provides a command for this: 


Use the CLS command to clear all displayed information from the display area. 
The format for this command is: 


cls 
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Recording information from the display area 
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The information shown in the display area of the COMMAND window can be 
written to a log file. The log file is a system file that contains commands you've 
entered, their results, and error or progress messages. To record this informa- 
tion in a log file, use the DLOG command. 


You can execute log files by using the TAKE command. When you use DLOG 
to record the information from the COMMAND window display area, the de- 
bugger automatically precedes all error or progress messages and command 
results with a semicolon to turn them into comments. This way, you can easily 
re-execute the commands in your log file by using the TAKE command. 


(_] To begin recording the information shown in the COMMAND window dis- 
play area, use: 


dlog filename 


This command opens a log file called filename that the information is re- 
corded into. 


[_} To end the recording session, enter: 


dlog close 


If necessary, you can write over existing log files or append additional informa- 
tion to existing files. The extended format for the DLOG command is: 


dlog filename [,{a | w}] 


The optional parameters of the DLOG command control how the log file is 
created and/or used: 


_] Creating a new log file. If you use the DLOG command without one of 
the optional parameters, the debugger creates a new file that it records the 
information into. If you are recording to a log file already, entering a new 
DLOG command and filename closes the previous log file and opens a 
new one. 


_.} Appending to an existing file. Use the a parameter to open an existing 
file to which to append the information in the display area. 


_] Writing over an existing file. Use the w parameter to open an existing 
file to write over the current contents of the file. Note that this is the default 
action if you specify an existing filename without using either the a or w 
options; you will lose the contents of an existing file if you don’t use the ap- 
pend (a) option. 
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4.2 Using the Menu Bar and the Pulldown Menus 


In all three of the debugger modes, you'll see a menu bar at the top of the 
screen. The menu selections offer you an alternative method for entering 
many of the debugger commands. Figure 4—2 points out the menu bar ina 
mixed-mode display. There are several ways to use the selections on the 
menu bar, depending on whether the selection has a pulldown menu or not. 


Figure 4—2. The Menu Bar in the Basic Debugger Display 


menu bar 


Load Break Watch Memory Color MoDe Pin Run=F5 Step=F8 Next=F10 
-—DISASSEMBLY -—CPU 1 
400000 Of2b0000 main: PUSH AR3 Arc 00£00076 SP 00000755 4 
400001 080b0014 LDI SP, AR3 RO 00000003 R1l 00000005 
400002 02740002 ADDI 2,SP R2 00000007 R3 00000000 
400003 0£f240000 PUSH R4 R4 00000000 R5 00000000 
400004 08640000 LDI 0,R4 R6 00000000 R7 00000000 
*. 
400005 15440301 STI R4, *+AR3 (1) ARO 00001802 AR1 00000000 
400006 15440302 STI R4, *+AR3 (2) 
AR2 00000000 AR3 00000000 
400007 62400057 CALL meminit v v 
AR4 00000000 AR5 00000000 
400008 08640000 LDI 0,R4 | 
AR6 0000000 AR7 00000000 
p—FILE: sample.c CALLS 
00037 extern struct zzz *func(): 4 1: **UNKNOWN 
00038 extern call(); 
00039 extern meminit (); 
00040 main() 
00041 { 
00042 register int i = 0; Yi 
00043 int j = 0, k = 0; | | 
Roading ¢s ample out 000000  0000004b 00000040 00000041 00000042 A 
Dore 000004 00000043 00000044 00000045 00000046 
fife sample.c 000008 00000047 00000048 00000049 o000004a V 
>>> [j] 00000c 00000000 00000000 00000000 00000000 


di 


Several of the selections on the menu bar have pulldown menus; if they could 
all be pulled down at once, they’d look like Figure 4-3. 


Figure 4—3. All of the Pulldown Menus (Basic Debugger Display) 
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Load Break Watch Memory Color Mode Pin 
Load Add Add Add Load Cc (auto) Connect 
Reload Delete Delete Delete Save Asm Disconnect 
Symbols Reset Reset Reset Config Mixed Dist 
REstart Lust RILEHE Border 
ReseT Enable Prompt 
File palalal 

Save 

Connect 

DisConn 

Note: The Connect and DisConn entries are available for the simulator only. 
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Note that the menu bar and associated pulldown menus occupy fixed positions 
on the display. Unlike windows, you can’t move, resize, or cover the menu bar 
or pulldown menus. 


Pulldown menus in the profiling environment 


The debugger displays a different menu bar in the profiling environment: 


_ 


Load mAp Mark Enable Disable Unmark View Stop-points Profile 


d 


The Load menu corresponds to the Load menu in the basic debugger environ- 
ment. The mAp menu provides memory map commands available from the 
basic Memory menu. The other entries provide access to profiling commands. 


Using the pulldown menus 


There are several ways to display the pulldown menus and then execute your 
selections from them. Executing a command from a menu is similar to execut- 
ing acommand by typing it in. 


__] If you select a command that has no parameters, then the debugger 
executes the command as soon as you select it. 


[_] If you select a command that has one or more parameters, the debugger 
displays a dialog box when you make your selection. A dialog box offers 
you the chance to type in the parameter values for the command. 


The following paragraphs describe several methods for selecting commands 
from the pulldown menus. 


Mouse method 1 


ms 1) Point the mouse cursor at one of the appropriate selections in the menu 
bar. 

il 2) Press the left mouse button, but don’t release the button. 

Al 3) While pressing the mouse button, move the mouse downward until your 


selection is highlighted on the menu. 


U0 4) When your selection is highlighted, release the mouse button. 
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Mouse method 2 
a 1) Point the cursor at one of the appropriate selections in the menu bar. 


tt 2) Click the left mouse button. This displays the menu until you are ready to 
make a selection. 


x 3) Point the mouse cursor at your selection on the pulldown menu. 


tt 4) When your selection is highlighted, click the left mouse button. 


Ikey| Keyboard method 1 


ALT 1) Press the key; don’t release it. 


& 
ts 


Press the key that corresponds to the highlighted letter in the selection 
name; release both keys. This displays the menu and freezes it. 


3) Press and release the key that corresponds to the highlighted letter of your 
selection in the menu. 


Keyboard method 2 
ALT 1) Press the key; don’t release it. 


OO 2) Press the key that corresponds to the highlighted letter in the selection 
name; release both keys. This displays the menu and freezes it. 


G@) @® 3) Use the arrow keys to move up and down through the menu. 


(2) 4) When your selection is highlighted, press @). 


Escaping from the pulldown menus 


(_] lf you display amenu and then decide that you don’t want to make a selec- 
tion from this menu, you can: 


M Press 
or 


MH Point the mouse outside of the menu; press and then release the left 
mouse button. 


(_] If you pull down a menu and see that it is not the menu you wanted, you 
can point the mouse at another entry and press the left mouse button, or 
you can use the and keys to display adjacent menus. 
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Using menu bar selections that don’t have pulldown menus 


U 


Ikey| (FB) 


(F8 ) 


F10 
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These three menu bar selections are single-level entries without pulldown me- 
nus: 


Run=F5 Step=F8 Next=F10 


There are two ways to execute these choices. 


1) Point the cursor at one of these selections in the menu bar. 


2) Click the left mouse button. 


This executes your choice in the same manner as typing in the associated 
command without its optional expression parameter. 


Pressing this key is equivalent to typing in the RUN command without an ex- 
pression parameter. 


Pressing this key is equivalent to typing in the STEP command without an ex- 
pression parameter. 


Pressing this key is equivalent to typing in the NEXT command without an ex- 
pression parameter. 


Using Dialog Boxes 


4.3 Using Dialog Boxes 


Many of the debugger commands have parameters. When you execute these 
commands from pulldown menus, you must have some way of providing pa- 
rameter information. The debugger allows you to do this by displaying a dialog 
box that asks for this information. 


Entering text in a dialog box 


Entering text in a dialog box is much like entering commands on the command 
line. For example, the Add entry on the Watch menu is equivalent to entering 
the WA command. This command has three parameters: 


wa expression [,[ label] [, display formal] 


When you select Add from the Watch menu, the debugger displays a dialog 
box that asks you for this parameter information. The dialog box looks like this: 


Watch Add 


Expression 
Label 


Format 
<<OK>> <Cancel> 


You can enter an expression just as you would if you were to type the WA com- 
mand; then press or @). The cursor moves down to the next parameter: 


Watch Add 
Expression MY_VAR 
Label 
Format 


<<OK>> <Cancel> 


When the dialog box displays more than one parameter, you can use the arrow 
keys to move from parameter to parameter. You can omit entries for optional 
parameters, but the debugger won’t allow you to skip required parameters. 


In the case of the WA command, the two parameters, /abe/and format, are op- 
tional. If you want to enter a parameter, you may do so; if you don’t want to use 
these optional parameters, don’t type anything in their fields—just continue to 
the next parameter. 
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Modifying text in a dialog box is similar to editing text on the command line: 


[_} When you display a dialog box for the first time during a debugging ses- 
sion, the parameter fields are empty. When you bring up the same dialog 
box again, though, the box displays the last values that you entered. (This 
is similar to having acommand history.) If you want to use the same value, 
just press or G) to move to the next parameter. 


[_} You can edit what you type (or values that remain from a previous entry) 
in the same way that you can edit text on the command line. See Section 
4.1 for more information on editing text on the command line. 


When you’ve entered a value for the final parameter, point and click on <OK> 
to save your changes, or <Cancel> to discard your changes; the debugger 
closes the dialog box and executes the command with the parameter values 
you supplied. You can also choose between the <OK> and <Cancel> options 
by using the arrow keys and pressing on your desired choice. 


4.4 Entering Commands From a Batch File 


8 take 
Se 
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You can place debugger commands in a batch file and execute the file from 
within the debugger environment. This is useful, for example, for setting up a 
memory map that contains several MA commands followed by a MAP com- 
mand that enables memory mapping. 


Use the TAKE command to tell the debugger to read and execute commands 
from a batch file. A batch file can call another batch file; they can be nested 
in this manner up to 10 deep. To halt the debugger’s execution of a batch file, 
press (ESC). 


The format for this command is: 
take batch filename [, suppress echo flag] 


_] The batch filename parameter identifies the file that contains commands. 


@ If you supply path information with the filename, the debugger looks 
for the file in the specified directory only. 


If you don’t supply path information with the filename, the debugger 
looks for the file in the current directory. 


mM OnPCsystems, ifthe debugger can'’tfind the file in the current directo- 
ry, it looks in any directories that you identified with the D_DIR environ- 
ment variable. You can set D_DIR within the DOS environment; the 
command for doing this is: 


SET D_DIR=pathname;pathname 
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This allows you to name several directories that the debugger can 
search. If you often use the same directories, it may be convenient to 
set D_DIR in your autoexec.bat file or initdb.bat file. On DOS systems, 
you can also set D_DIR from within the debugger by using the SYS- 
TEM command (see Section 4.6, Entering Operating-System Com- 
mands, page 4-19). 


[(_} By default, the debugger echoes the commands in the COMMAND win- 
dow display area and updates the display as it reads commands from the 
batch file. 


H If you don’t use the suppress echo flag parameter, or if you use it but 
supply a nonzero value, then the debugger behaves in the default 
manner. 


H |f you would like to suppress the echoing and updating, use the value 0 
for the suppress echo flag parameter. 
Echoing strings in a batch file 


When executing a batch file, you can display a string to the COMMAND win- 
dow by using the ECHO command. The syntax for the command is: 


echo string 
This displays the string in the COMMAND window display area. 
For example, you may want to document what is happening during the execu- 


tion of a certain batch file. To do this, you could use the following line in your 
batch file to indicate that you are creating anew memory map for your device: 


echo Creating new memory map 


(Notice that the string should not be in quotes.) 


When you execute the batch file, the following message appears: 


Creating new memory map 


Note that any leading blanks in your string are removed when the ECHO com- 
mand is executed. 
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Controlling command execution in a batch file 


In batch files, you can control the flow of debugger commands. You can 
choose to execute debugger commands conditionally or set up alooping situa- 
tion by using IF/ELSE/ENDIF or LOOP/ENDLOOP, respectively. 


(_} To conditionally execute debugger commands in a batch file, use the 
IF/ELSE/ENDIF commands. The syntax is: 


if Boolean expression 
debugger command 
debugger command 


[else 

debugger command 

debugger command 

| 

endif 

The debugger includes some predefined constants for use with IF. These 


constants evaluate to 0 (false) or 1 (true). Table 4-1 shows the constants 
and their corresponding tools. 


Table 4—1. Predefined Constants for Use With Conditional Commands 
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Constant Debugger Tool 
$$EMUS$$ emulator 
$$EVM$$ evaluation module 
$$SIM$$ simulator 


If the Boolean expression evaluates to true (1), the debugger executes all 
commands between the IF and ELSE or ENDIF. Note that the ELSE por- 
tion of the command is optional. (Gee Chapter 12 for more information 
about expressions and expression analysis.) 
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One way you can use these predefined constants is to create an initializa- 
tion batch file that works for any debugger tool. This is useful if you are us- 
ing, for example, both the emulator and the EVM. To do this, you can set up 
the following batch file: 


if SSEMU$$ 

echo Invoking initialization batch file for emulator. 
use \c3xhll 

take emuinit.cmd 


endif 
if S$SEVMS$$ 
echo Invoking initialization batch file for EVM. 


use \c3xhll 
take evminit.cmd 


endif 


In this example, the debugger will execute only the initialization com- 
mands that apply to the debugger tool that you invoke. 


To set up a looping situation to execute debugger commands in a batch 
file, use the LOOP/ENDLOOP commands. The syntax is: 


loop expression 
debugger command 
debugger command 


endloop 
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These looping commands evaluate in the same method as in the run 
conditional command expression. (See Chapter 12 for more information 
about expressions and expression analysis.) 


If you use an expression that is not Boolean, the debugger evaluates 
the expression as a loop count. For example, if you wanted to execute 
a sequence of debugger commands ten times, you would use the fol- 
lowing: 


loop 10 
runb 


endiees 
The debugger treats the 10 as a counter and executes the debugger 
commands ten times. 


If you use a Boolean expression, the debugger executes the com- 
mands repeatedly as long as the expression is true. This type of ex- 
pression has one of the following operators as the highest precedence 
operator in the expression: 


> >= < 


&& I | 


For example, if you want to trace some register values continuously, 
you can set up a looping expression like the following: 


loop !0 
step 
7 Pe 
? ARO 
endloop 


The IF/ELSE/ENDIF and LOOP/ENDLOOP commands work with the follow- 
ing conditions: 


LL} 
LL} 


You can use conditional and looping commands in a batch file only. 


You must enter each debugger command on a separate line in the batch 
file. 


You can’t nest conditional and looping commands within the same batch 
file. 
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4.5 Defining YourOwn Command Strings 


The debugger provides a shorthand method of entering often-used com- 
mands or command sequences. This process is called aliasing. Aliasing en- 
ables you to define an alias name for the command(s) and then enter the alias 
name as if it were a debugger command. 


To do this, use the ALIAS command. The syntax for this command is: 
alias [alias name [, “command string’) | 


The primary purpose of the ALIAS command is to associate the alias name 
with the debugger command you've supplied as the command string. Howev- 
er, the ALIAS command is versatile and can be used in several ways: 


_} Aliasing several commands. The command string can contain more 
than one debugger command—just separate the commands with semico- 
lons. 


For example, suppose you always began a debugging session by loading 
the same object file, displaying the same C source file, and running to a 
certain point in the code. You could define an alias to do all these tasks at 
once: 


alias init,”load test.out;file source.c;go main” 


Now you could enter init instead of the three commands listed within the 
quote marks. 


(_] Supplying parameters to the command string. The command string 
can define parameters that you’ll supply later. To do this, use a percent 
sign and a number (%1) to represent the parameter that will be filled in lat- 
er. The numbers should be consecutive (%1, %2, %3) unless you plan to 
reuse the same parameter value for multiple commands. 


For example, suppose that every time you filled an area of memory you 
also wanted to display that block in the MEMORY window: 

alias mfil,”fill %1, %2, S3;mem %1” 

Then you could enter: 

mfil 0x014,0x18,0x11112222 


The first value (0x014) would be substituted for the first FILL parameter 
and the MEM parameter (%1). The second and third values would be sub- 
stituted for the second and third FILL parameters (%2 and %3). 


(_] Listing all aliases. To display a list of all the defined aliases, enter the 
ALIAS command with no parameters. The debugger will list the aliases 
and their definitions in the COMMAND window. 
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For example, assume that the init and mfil aliases had been defined as 
shown in the previous two examples. If you entered: 


alias 
you’d see: 
Alias Command 
IEIN/AEAP -—-> load test.out;file source.c;go main 
MFIL —-> fi11 %$1,%2,%3;mem $1 


(_] Finding the definition of an alias. If you Know an alias name but are not 
sure of its current definition, enter the ALIAS command with just an alias 
name. The debugger will display the definition in the COMMAND window. 


For example, if you had defined the init alias as shown in the first example 
above, you could enter: 

alias init 

Then you'd see: 


‘sone aliasedas ”"loadtest.out; file source.c;go cae 


_} Nesting alias definitions. You can include a defined alias name in the 
command string of another alias definition. This is especially useful when 
the command string would be longer than the debugger command line. 


[|_| Redefining an alias. To redefine an alias, re-enter the ALIAS command 
with the same alias name and a new command string. 


|_| Deleting aliases. To delete a single alias, use the UNALIAS command: 
unalias alias name 


To delete a// aliases, enter the UNALIAS command with an asterisk 
instead of an alias name: 
unalias * 


Note that the * symbol does not work as a wildcard. 


Note: 


[_] Alias definitions are lost when you exit the debugger. If you want to reuse 
aliases, define them in a batch file. 


[_] Individual commands within a command string are limited to an expand- 
ed length of 132 characters. The expanded length of the command in- 
cludes the length of any substituted parameter values. 
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4.6 Entering Operating-System Commands (DOS Only) 


The debugger provides a simple method for entering DOS commands without 
explicitly exiting the debugger environment. To do this, use the SYSTEM com- 
mand. The format for this command is: 


system [DOS command |, flag] | 


The SYSTEM command behaves in one of two ways, depending on whether 
or not you supply an operating-system command as a parameter: 


[_] Ifyou enter the SYSTEM command with aDOS command as a parameter, 
then you stay within the debugger environment. 


[_] If you enter the SYSTEM command without parameters, the debugger 
opens a system shell. This means that the debugger will blank the debug- 
ger display and temporarily exit to the operating-system prompt. 


Use the first method when you have only one command to enter; use the se- 
cond method when you have several commands to enter. 


Entering a single command from the debugger command line 


If you need to enter only a single DOS command, supply it as a parameter to 
the SYSTEM command. For example, if you want to copy a file from another 
directory into the current directory, you might enter: 

system "copy a:\backup\sample.c sample.c” 

If the DOS command produces a display of some sort (such as a message), 
the debugger will blank the upper portion of the debugger display to show the 
information. In this situation, you can use the flag parameter to tell the debug- 
ger whether or not it should hesitate after displaying the results of the DOS 
command. Flag may be aO ora 1: 


0 The debugger immediately returns to the debugger environment after 
the last item of information is displayed. 


1 The debugger does not return to the debugger environment until you 
press @). (This is the default.) 


Inthe example above, the debugger would open a system shell to display the 
following message: 


1 File(s) copied 
Type Carriage Return To Return To Debugger 


The message would be displayed until you pressed @). 


If you wanted the debugger to display the message and then return immediate- 
ly to the debugger environment, you could enter the command in this way: 


system "copy a:\backup\sample.c sample.c”,0 
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Entering several commands from a system shell 


If you need to enter several commands, enter the SYSTEM command without 
parameters. The debugger will open a system shell and display the DOS 
prompt. At this point, you can enter any DOS command. 


When you are finished entering commands and are ready to return to the de- 
bugger environment, enter: 


exit 


ae, 
Note: 


Available memory limits the DOS commands that you can enter from a sys- 
tem shell. For example, you will not be able to invoke another version of the 
debugger. 


ss | 


Additional system commands 


= 
eS 


or 


dir 
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The debugger also provides separate commands for changing directories and 
for listing the contents of a directory. 


Use the CHDIR (CD) command to change the current working directory. The 
format for this command is: 


chdir directory name 
cd_ directory name 


This changes the current directory to the specified directory name. You can 
use relative pathnames as part of the directory name. Note that this command 
can affect any command whose parameter is a filename (such as the FILE, 
LOAD, and TAKE commands). 


Use the DIR command to list the contents of a directory. The format for this 
command is: 


dir [directory name] 


This commanddisplays a directory listing inthe display area of the COMMAND 
window. If you use the optional directory name parameter, the debugger dis- 
plays a list of the specified directory’s contents. If you don’t use this parameter, 
the debugger lists the contents of the current directory. 


You can use wildcards as part of the directory name. 


Chapter 5 


Defining a Memory Map 


Before you begin a debugging session, you must supply the debugger with a 
memory map. The memory map tells the debugger which areas of memory it 
can and can’t access. Note that the commands described in this chapter can 
also be entered by using the Memory pulldown menu. 
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The Memory Map: What It Is and Why You Must Define It 


5.1 The Memory Map: What It Is and Why You Must Define It 


A memory map tells the debugger which areas of memory it can and can’t ac- 
cess. Memory maps vary, depending on the application. Typically, the map 
matches the MEMORY definition in your linker command file. 


Note: 


When the debugger compares memory accesses against the memory map, 
it performs this checking in software, not hardware. The debugger can’t pre- 


vent your program from attempting to access nonexistent memory. 
sss | 


A special default initialization batch file included with the debugger package 
defines a memory map for your version of the debugger. This memory map 
may be sufficient when you first begin using the debugger. However, the de- 
bugger provides a complete set of memory-mapping commands that let you 
modify the default memory map or define a new memory map. 


You can define the memory map interactively by entering the memory-map- 
ping commands while you’re using the debugger. This can be inconvenient be- 
cause, in most cases, you'll set up one memory map before you begin debug- 
ging and willuse this map for all of your debugging sessions. The easiest meth- 
od for defining a memory map is to put the memory-mapping commands in a 
batch file. 


Defining the memory map in a batch file 
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There are two methods for defining the memory map in a batch file: 


[_.] You can redefine the memory map defined in the initialization batch file. 


[_] You can define a memory map in a separate batch file of your own. 


When you invoke the debugger, it follows these steps to find the batch file that 
defines your memory map: 


1) Itchecks to see whether you’ve used the -t debugger option. The -t option 
allows you to specify a batch file other than the initialization batch file 
shipped with the debugger. If it finds the -t option, the debugger reads and 
executes the specified file. 


2) Ifyou don’t use the -t option, the debugger looks for the default initializa- 
tion batch file called init.cmd. If the debugger finds this file, it reads and 
executes the commands. 
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Potential memory map problems 


You may experience these problems if the memory map isn’t correctly defined 
and enabled: 


[_} Accessing invalid memory addresses. If you don’t supply a batch file 
containing memory-map commands, then the debugger is initially unable 
to access any target memory locations. Invalid memory addresses and 
their contents are highlighted in the data-display windows. (On color moni- 
tors, invalid memory locations, by default, are displayed in red.) 


[_} Accessing an undefined or protected area. When memory mapping is 
enabled, the debugger checks each of its memory accesses against the 
memory map. If you attempt to access an undefined or protected area, the 
debugger displays an error message. 


(_] Loading aCOFF file with sections that cross amemory range. Be sure 
that the map ranges you specify ina COFF file match those that you define 
with the MA command (described on page 5-7). Alternatively, you can 
turn memory mapping off during a load by using the MAP OFF command 
(see page 5-9). 
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5.2 Sample Memory Maps 


Because you must define a memory map before you can run any programs, 
i's convenient to define the memory map in the initialization batch files. 
Figure 5—1 (a), Figure 5—2 (a), and Figure 5-3 (a) show the memory com- 
mands that are redefined in the initialization batch file that accompanies the 
simulator, emulator, and EVM, respectively. You can use any of the files as they 
are, edit them, or create your own memory map batch files. 


The MA (map add) commands define valid memory ranges and identify the 
read/write characteristics of the memory ranges. The MAP command enables 
mapping (note that by default, mapping is enabled when you invoke the de- 
bugger). Figure 5-1 (b), Figure 5-2 (b), and Figure 5-3 (b) illustrate the 
memory map defined by the default initialization batch file. 


Figure 5—1. Sample Memory Map for Use With a ’C3x Simulator 


(a) Memory map commands (init.cmd) (b) Memory map for ’C3x local memory 
MA 0x000000, 0x1000,ROM = eae Internal ROM 
MA 0x808000,0x0010, RAM 0x001000 
MA 0x808020,0x0400, RAM eB 0x807F FE reserved 
MA 0x809800,0x0800, RAM 0x808000 
MAP ON to Ox80800F Memory Map Register 1 
0x808010 
to 0x80801F psenied 
io eae ee Memory Map Register 2 
0x808420 reserved 
to 0x8097FF 
0x809800 Internal RAM 
to Ox809FFF 
0x80A000 reserved 
to OxFFFFFF 


The ’C8x application board can be used as a target system with the ’C3x emu- 
lator. Figure 5—2 (page 5-5) shows a sample memory map for the application 
board. 


Sample Memory Maps 


Figure 5-2. Sample Memory Map for Use With a ’C3x Application Board / Emulator 


(a) Memory map commands (init.cmd) (b) Memory map for ’C3x local memory 
MA 0x000000,0x000800, ROM 0x000000 EPROM 
MA 0x400000, 0x080000, RAM to Basis 
MA 0x800000, 0x002000, RAM x reserved 
MA 0x804000, 0x001000, RAM to alee 
MA 0x805f£7,0x000009, RAM x DRAM 
MA 0x808000, 0x000010, RAM to aes 

x reserved 
ve tee oy RAM io epee 
x808030, 0x000010, RAM 
MA 0x808040,0x000010, RAM e eeIEEE SRAM1 
MA 0x808050,0x000010, RAM Gagenan 
MA 0x808060,0x000001, RAM to 0x803FFF reserved 
MA 0x808064, 0x000001, RAM a 
MA 0x809800,0x000400, RAM to Ox804EFF DPRAM 
MA 0xF00000, 0x004000, RAM to 0x805FF6 reserved 
MAP ON 
Ox805FF7 
to Ox805FEF DPSEM 
0x806000 
to 0x807FFF reserved 
0x808000 DMA 
to Ox80800F 
0x808010 reserved 
to 0x80801F 
0x808020 , 
to 0x80802F need 
0x808030 : 
to 0x80803F Timer 1 
0x808040 : 
to 0x80804F Serial Port 0 
0x808050 : 
to 0x80805F Serial Port 1 
0x808060 XBUSCTL 
0x808061 
to 0x808063 ay wid 
0x808064 PBUSCTL 
0x808065 
to 0x8097FF reserved 
0x809800 ; 
to 0x809BEE C3x Internal RAM Block 0 
0x809C00 ; 
to Ox809FFF C3x Internal RAM Block 1 
Ox80A000 
to OxEFFFFF bebe 
OxFO0000 
to OxFOSFFF ssluinig 
OxF04000 
to OXFFFFFF Lr pas 
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Figure 5-3. Sample Memory Map for Use With a 'C3x EVM 


(a) Memory map commands (init.cmd) 


MA 0x000000,0x004000, 
MA 0x804000,0x001000, 
MA 0x808000,0x000010, 
MA 


MAP ON 


MA 0x808020,0x000010, 
MA 0x808030,0x000010, 
MA 0x808040,0x000010, 
MA 0x808050,0x000010, 
MA 0x808060,0x000001, 
MA 0x808064,0x000001, 
MA 0x809800,0x000400, 


RAM 
RAM 
RAM 
RAM 
RAM 
RAM 
RAM 
RAM 
RAM 
RAM 


MA 0x809C00,0x000400, 


RAM 
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(b) Memory map for ’C3x local memory 


to 


to 


to 


to 


to 


0x000000 
0x003FFF 
0x004000 
0x803F FF 
0x804000 
0x804FFF 
0x805000 
0x807F FF 
0x808000 
Ox80800F 
0x808010 
0x80801F 
0x808020 
0x80802F 
0x808030 
0x80803F 
0x808040 
0x80804F 
0x808050 
Ox80805F 


0x808060 


0x808061 
0x808063 


0x808064 


0x808065 
0x8097FF 
0x809800 
Ox809BFF 
0x809C00 
Ox809F FF 


0x80A000 
OxFFFFFF 


SRAM 


reserved 


Communication Port 


reserved 


DMA 


reserved 


Timer 0 


Timer 1 


Serial Port 0 


Serial Port 1 


XBUSCTL 


reserved 


PBUSCTL 


reserved 


*C3x Internal RAM Block 0 


*C3x Internal RAM Block 1 


reserved 


Identifying Usable Memory Ranges 


5.3 Identifying Usable Memory Ranges 


me 
<a 


The debugger’s MA (memory add) command identifies valid ranges of target 
memory. The syntax of the MA command is: 


ma address, length, type 


_] The address parameter defines the starting address of a range. This pa- 
rameter can be an absolute address, any C expression, the name of a C 
function, or an assembly language label. 


A new memory map must not overlap an existing entry. If you define a 
range that overlaps an existing range, the debugger ignores the new 


range and displays this error message in the COMMAND window display 
area: 


Conflicting map range 


__] The length parameter defines the length of the range. This parameter can 
be any C expression. 


[_] The type parameter identifies the read/write characteristics of the memory 
range. The type must be one of these keywords: 


Use this keyword as the type 


To identify this kind of memory, parameter 
Read-only memory R or ROM 
Write-only memory W or WOM 
Read/write memory R|W or RAM 
No-access memory PROTECT 
Input port IPORT 
Output port OPORT 
Input/output port IOPORT 
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Notes: 


(_} The debugger caches memory that is not defined as a port type (IPORT, 
OPORT, or IOPORT). For ranges that you don’t want cached, be sure 
to map them as ports. 


(_] When you are using the simulator, you can use the parameter values 
IPORT, OPORT, and IOPORT to simulate I/O ports. See Section 5.9, 
Simulating I/O Space. 


[(_] Be sure that the map ranges that you specify ina COFF file match those 
that you define with the MA command. Moreover, a command sequence 
such as: 


ma X,y,ram; ma x+y,zZ,ram 

doesn’t equal 

ma X,y+z,ram 

If you were planning to load a COFF block that spanned the length of 
y + Z, you should use the second MA command example. Alternatively, 


you could turn memory mapping off during aload by using the MAP OFF 


command. 
eee ee ee ee eee eee eee 


Memory mapping with the simulator 


Unlike the emulator and EVM, the ’C3x simulator has memory cache capabili- 
ties that allow you to allocate as much memory as you need. However, to use 
memory cache capabilities effectively with the ’C3x, do not allocate more than 
20K words of memory in your memory map. For example, the following 
memory map allocates 64K words of ’C3x program memory. 


Example 5—1.Sample Memory Map for the TMS320C3x Using Memory Cache Capabilities 
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IA 0,0,R|W 

IA 0x5000,0x5000,R|W 
1X 0xa000,0x5000,R|W 
MA 0xf000,0x5000,R|W 


Kc 


The simulator creates temporary files in a separate directory on your disk. For 
example, when you enter an MA (memory add) command, the simulator 
creates a temporary file in the root directory of your current disk. Therefore, 
if you are currently running your simulator on the C drive, temporary files are 
placed in the C:\ directory. This prevents the processor from running out of 
memory space while you are executing the simulator. 


Identifying Usable Memory Ranges / Enabling Memory Mapping 


F< ———S—__ ™”’”'™:™”———=——“OwVw_—=—waoa_——Q0.0“Q.GSQ-j(.— . .  . 4 
Note: 


If you execute the simulator from a floppy drive (for example, drive A), the 


temporary files will be created in the A:\ directory. 
| | 


Alltemporary files are deleted when you leave the simulator via the QUIT com- 
mand. If, however, you exit the simulator with a soft reboot of your computer, 
the temporary files will not be deleted; you must delete these files manually. 
(Temporary files usually have numbers for names.) 


Your memory mapis restricted only by your PC’s capabilities. As a result, there 
should be sufficient free space on your disk to run any memory map you want 
to use. If you use the MA command to allocate 20K words (80K bytes) of 
memory in your memory map, then your disk should have at least 80K bytes 
of free space available. To do this, you can enter: 


ma 0x80a000, 0x5000, ram 


5.4 Enabling Memory Mapping 


<4 


or 


By default, mapping is enabled when you invoke the debugger. In some 
instances, you may want to explicitly enable or disable memory. You can use 
the MAP command to do this; the syntax for this command is: 


map on 
map off 


Note that disabling memory mapping can cause bus fault problems in the tar- 
get because the debugger may attempt to access nonexistent memory. 


Note: 
When memory mapping is enabled, you cannot: 


[_} Access memory locations that are not defined by an MA command. 


|_| Modify memory areas that are defined as read only or protected. 


If you attempt to access memory in these situations, the debugger displays 
this message in the COMMAND window display area: 


Error in expression 
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5.5 Checking the Memory Map 


~@ ml If you want to see which memory ranges are defined, use the ML command. 
The syntax for this command is: 


ml 


The ML command lists the starting address, ending address, and read/write 
characteristics of each defined memory range. For example, if you're using the 
default memory map for the emulator and you enter the ML command, the de- 
bugger displays this: 


Memory Range Attributes 
00000000 OOO00O07£E READ 
00400000 O047ffff REA 
00800000 OOO EEE REA 
00804000 O0804ffft REA 
O0805f£7 O0805ffFf REA! 
00808000 O080800Ff REA! 
00808020 0080802f REA! 
00808030 0080803f REA 
00808040 0080804f REA 
00808050 O0080805f REA 
00808060 REA 
00808064 REA 
00809800 O0809bff REA 


RITE 
Bulga 
RITE 
RITE 
RITE 
Rens 
RuDSIERs 
RITE 
RITE 
RITE 
RITE 
REE: 


starting —— 
address 


Bis tie eo iolisisits ie ee 
SSeS eae 


ending 
address 
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Modifying the Memory Map During a Debugging Session 


5.6 Modifying the Memory Map During a Debugging Session 


md 


ma 


If you need to modify the memory map during a debugging session, use these 
commands. 


To delete a range of memory from the memory map, use the MD (memory de- 
lete) command. The syntax for this command is: 


md_ address 


The address parameter identifies the starting address of the range of memory. 
If you supply an address that is not the starting address of a range, the debug- 
ger displays this error message in the COMMAND window display area: 


Specified map not found 


a a | 
Note: 


If you are using the simulator and want to use the MD command to remove 
a simulated I/O port, you must first disconnect the port with the MI command. 
Refer to Section 5.9, page 5-13. 


| es) 


If you want to delete all defined memory ranges from the memory map, use 
the MR (memory reset) command. The syntax for this command is: 


mr 


This resets the debugger memory map. 


If you want to add a memory range to the memory map, use the MA (memory 
add) command. The syntax for this command is: 


ma_ address, length, type 


The MA command is described in detail on page 5-7. 
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Returning to the original memory map 


If you modify the memory map, you may want to go back to the original memory 
map without quitting and reinvoking the debugger. You can do this by resetting 
the memory map and then using the TAKE command to read in your original 
memory map from a batch file. 


Suppose, for example, that you had set up your memory map in a batch file 
named mem.map. You could enter these commands to go back to this map: 
mr Reset the memory map 
take mem.map Reread the default memory map 
The MR command resets the memory map. (Note that you could put the MR 
command in the batch file, preceding the commands that define the memory 
map.) The TAKE command tells the debugger to execute commands from the 
specified batch file. 


5.7 Using Multiple Memory Maps for Multiple Target Systems 


If you’re debugging multiple applications, you may need a memory map for 
each target system. Here’s the simplest method for handling this situation. 


Step 1: Let the initialization batch file define the memory map for one of your 
applications. 


Step 2: Create a separate batch file that defines the memory map for the 
additional target system. The filename is unimportant, but for the 
purposes of this example, assume that the file is named filename.x. 
The general format of this file’s contents should be: 


mr Reset the memory map 
MA commands Define the new memory map 
map on Enable mapping 
(Of course, you can include any other appropriate commands in this 
batch file.) 


Step 3: Invoke the debugger as usual. 

Step 4: The debugger reads initialization batch file as usual. Before you be- 
gin debugging, read in the commands from the new batch file: 
take filename.x 
This redefines the memory map for the current debugging session. 
You can also use the -t option instead of at the TAKE command 
when you invoke the debugger. The -t option allows you to specify 


a new batch file to be used instead of the default initialization batch 
file. 


Simulating Serial Ports (Simulator Only) / Simulating I/O Space (Simulator Only) 


5.8 Simulating Serial Ports (Simulator Only) 


The simulator supports serial port simulation with the global port control regis- 
ter, the FSX/DX/CLKX port control register, and the FSR/DR/CLKR port con- 
trol register. 


The simulator supports serial port I/O transfers on a limited basis. Because the 
simulator does not support any external signals, you can simulate serial port 
operations only by using the internal serial clocks. You must also enable the 
DR and DX pins as the serial receive pin and serial transmit pin, respectively. 


To enable the internal clocks for both transmit and receive operations, you 
must ensure that the XCLKSRCE and RCLKSRCE bits of the global port con- 
trol register are set to 1. To enable the DX and DR pins for serial transmit and 
receive, set both the DXFUNC bit (in the FSX port control register) and the 
DRFUNC bit (in the FSR port control register) to 1. 


5.9 Simulating I/O Space (Simulator Only) 


In addition to adding memory ranges to the memory map, you can use the MA 
command to add I/O ports to the memory map. To do this, use IPORT (input 
port), OPORT (output port), or IOPORT (input/output port) as the memory 
type. Then, you can use the MC command to connect a port to an input or out- 
put file. This simulates external I/O cycle reads and writes by allowing you to 
read data in from a file and/or write data out to a file. 


Connecting an I/O port 


me 
<4 


The MC (memory connect) command connects IPORT, OPORT, or IOPORT 
to an input or output file. Before you can connect the port, you must add it to 
the memory map with the MA command. The syntax for this command is: 


mc_ port address, filename, {READ | WRITE} 


[_} The port address parameter defines the address of the I/O port. This pa- 
rameter can be an absolute address, any C expression, the name of a C 
function, or an assembly language label. 


[__] The filename parameter can be any filename. If you connect a port to read 
from a file, the file must exist, or the MC command will fail. 


_] The final parameter is specified as READ or WRITE and defines how the 
file will be used (for input or output, respectively). 
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The file is accessed as an LDI or STl instruction accesses the associated port 
address. Any port in I/O space can be connected to a file. A maximum of one 
input and one output file can be connected to a single port; multiple ports can 
be connected to a single file. Memory-mapped ports can also be connected 
to files; any instruction that reads or writes to the memory-mapped port will 
read or write to the associated file. 


eS | 


Note: 


When using the MS-DOS version of the simulator, you can connect a maxi- 
mum of 15 ports. 


| 


Example 5-2 shows how an input port can be connected to an input file named 
in.dat. 


Example 5—2.Connecting an Input Port to an Input File 


Assume that the file in.dat contains words of data in hexadecimal format, 
one per line, like this: 


0x0A000000 
0x10000000 
0x20000000 


These two debugger instructions set up and connect an input port: 


MA 0x50,0x1, IPORT Configure port address 50h 
as an input port 
MC 0x50, in.dat, READ Open file in.dat and 


connect to port address 50h 


Assume that this ’C3x instruction is part of your ’C3x program. This reads 
the data from the file in.dat. 


Di @50h, RO LDI instruction reads from the file 
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Configuring memory to use serial port simulation 


In order to use the serial port simulation, you must configure memory with the 
MA and MC commands. The following example adds the transmit and receive 
registers to the memory map and then connects their input and output to a file: 


Example 5-3. Adding Serial Port 0 Transmit and Receive Registers; Connecting Their 
Input and Output to a File 


ma 0x808020,0x27,RAM ;Configure all control registers 
ma 0x808048, 0x1,OPORT ;Configure DTR as output port 
ma 0x80804C, 0x1, IPORT ;Configure DRR as input port 


ma 0x808050,0x350, RAM ;Configure other MMR registers 
mc 0x808048,xdat,WRITE ;Open file xdat and connect to port address 


mc 0x80804C, rdat, READ ;Open file rdat and connect to port address 


70x808048h 


70x80804C 


The following commands configure the global port control, FSX/DX/CLKX port 
control register, and FSR/DR/CLKR port control register of serial port 0 for a 
8-bit transmit and receive operations: 

?*0x808040=0x000000C0 


2?*0x808042=0x00000010 
2?*0x808043=0x00000010 


The input and output file formats for the standard serial port operation require 
one hexadecimal number per line. The following is an acceptable format for 
an input file to the standard serial port: 

0x00000000 


0xA4450000 
0x099F0000 


Disconnecting an I/O port 


Before you can use the MD command to delete a port from the memory map, 
you must use the MI command to disconnect the port. 


The MI (memory disconnect) command disconnects a file from an I/O port. The 
syntax for this command is: 


mi port address, {READ | WRITE} 


The port address identifies the port that will be closed. The read/write charac- 
teristics must match the parameter used when the port was connected. 
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5.10 Simulating External Interrupts (Simulator Only) 


The ’C3x simulator allows you to simulate and monitor external interrupt 
signals and to specify at what clock cycle you want an interrupt to occur. To do 
this, you create a data file and connect it to one of the four interrupt pins, 
INTO-INTS. 


Note: 


The time interval is expressed as a function of CPU clock cycles. Simulation 


begins at the first clock cycle. 
now OhOo}eNToeoo 


Setting up your input file 


In order to simulate interrupts, you must first set up an input file that lists inter- 
rupt intervals. Your file must contain a clock cycle in the following format: 


clock cycle... [(clock cycle...) rpt {n | EOS}] 


(_} The clock cycle parameter represents the CPU clock cycle where you 
want an interrupt to occur. 


You can have two types of CPU clock cycles: 


H Absolute. To use an absolute clock cycle, your cycle value must rep- 
resent the actual CPU clock cycle where you want to simulate an inter- 
rupt. For example: 


12 34 56 


Interrupts are simulated at the 12th, 34th, and 56th CPU clock cycles. 
Notice that no operation is done to the clock cycle value; the interrupt 
occurs exactly as the clock cycle value is written. 


HM Relative. You can also select aclock cycle that is relative to the time at 
which the last event occurred. For example: 


12 +34 55 


In this example, a total of three interrupts are simulated at the 12th, 
46th (12+34), and 55th CPU clock cycles. A plus sign (+) before a 
clock cycle adds that value to the total clock cycles preceding it. 
Notice that you can mix both relative and absolute values in your input 
file. 


Simulating External Interrupts (Simulator Only) 


_] The rpt {n | EOS} parameter is optional and represents a repetition value. 
You can have two forms of repetition to simulate interrupts: 


Hi Repetition on a fixed number of times. You can format your input 
file to repeat a particular pattern for a fixed number of times. For 
example: 


5 (+10 +20) rpt 2 


The values inside of the parenthesis represent the portion that is 
repeated. Therefore, an interrupt is simulated at the 5th CPU cycle, 
then the15th (5+10), 35th (15+20), 45th (35+10), and 65th (45+20) 
CPU clock cycles. 


Note that n is a positive integer value. 


HM Repetition to the end of simulation. To repeat the same pattern 
throughout the simulation, add the string EOS to the line. For example: 


10 (+5 +20) rpt EOS 


Interrupts are simulated at the 10th CPU cycle, then the 15th (10+5), 
35th =(15+20), 40th (35+5), 60th (40+20), 65th (60+5), and 85th 
(65+20) CPU cycles, continuing in that pattern until the end of 
simulation. 


Defining a Memory Map 5-17 


Simulating External Interrupts (Simulator Only) 


Programming the simulator 


After you have created your input file, you can use debugger commands to: 


[_| Connect the interrupt pin to your input file 
[_] List the interrupt pins 
[.} Disconnect the interrupt pin from your input file 


Use these commands as described below, or use them from the PIN pulldown 
menu. 


pinc Toconnect your input file to the interrupt pin, use the following command: 
<a 


pinc pinname, filename 


[|_| The pinname parameter identifies the pin and must be one of the four ex- 
ternal interrupt pins (INTO-INT3). 


(| The filename parameter is the name of your input file. 


Example 5—4 shows you how to connect your input file by using the PINC com- 
mand. 


Example 5—4. Connecting the Input File With the PINC Command 


Suppose you want to simulate external interrupts at the 12th, 34th, 56th, 
and 89th clock cycles. 


First, create a input file with an arbitrary name such as myfile that contains 
the following line: 


ZS dG 89 


Then use the PINC command in the pin pulldown menu to connect the in- 
put file to the INT2 pin. 


pinc myfile, int2 Connects your data file 
to the specific interrupt pin 


This command connects myfile to the INT2 pin. Asa result, the debugger 
simulates an INT2 external interrupt at the 12th, 34th, 56th, and 89th clock 
cycles. 


pinl 


pind 


Simulating External Interrupts (Simulator Only) 
To verify that your input file is connected to the correct pin, use the PINL 
command. The syntax for this command is: 
pinl 
The PINL command displays all of the unconnected pins first, followed by the 


connected pins. For a connected pin, the simulator displays the name of the 
pin and the absolute pathname of the file in the COMMAND window. 


[— COMMAND 
PIN FILENAME 
INTO NULL 
INT1 NULL 
INT3 NULL 
INT2 /320h11/myfile 
>>> 


When you want to connect another file to an interrupt pin, the PINL command 
is useful for looking up an unconnected pin. 


To end the interrupt simulation, you must disconnect the pin. You can do this 
with the following command: 

pind pinname 

The pinname parameter identifies the interrupt pin and must be one of the four 
interrupt pins ( INTO-INT3 ). The PIND command detaches the file from the 


interrupt pin. After executing this command, you can connect another file to the 
same pin. 
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Loading, Displaying, and 
Running Code 


The main purpose of a debugging system is to allow you to load and run your 
programs in a test environment. This chapter tells you how to load your pro- 
grams into the debugging environment, run them on the target system, and 
view the associated source code. Many of the commands described in this 
chapter can also be executed from the Load pulldown menu. 
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6.1 Code-Display Windows: 
Viewing Assembly Language Code, C Code, or Both 


The debugger has three code-display windows: 


[_.} The DISASSEMBLY window displays the reverse assembly of program 
memory contents. 


|_| The FILE window displays any text file; its main purpose is to display C 
source files. 


|_| The CALLS window identifies the current function (when C code is run- 
ning). 


You can view code in several different ways. The debugger has three different 
code displays that are associated with the three debugging modes. The de- 
bugger’s selection of the appropriate display is based on two factors: 


[_] The mode you select, and 


[_] Whether your program is currently executing assembly language code or 
C code. 


Here’s asummary of the modes and displays; for a complete description of the 
three debugging modes, refer to Section 3.1, Debugging Modes and Default 
Displays (page 3-2). 


The debugger uses these 
Use this mode _ To view code-display windows 


assembly mode assembly language code only (i DISASSEMBLY 
(even if your program is 
executing C code) 


auto mode assembly language code L} DISASSEMBLY 
(when that’s what your 
program is running) 


auto mode C code only O FILE 
(when that’s what your OY CALLS 
program is running) 


mixed mode both assembly language and 4 DISASSEMBLY 
C code O FILE 


O CALLS 


You can switch freely between the modes. If you choose auto mode, then the 
debugger displays C code or assembly language code, depending on the type 
of code that is currently executing. 
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Selecting a debugging mode 


UU 


When you first invoke the debugger, it automatically comes up in auto mode. 
You can then choose assembly or mixed mode. There are several ways to do 
this. 


The Mode pulldown menu provides an easy method for 
switching modes. There are several ways to use the 
pulldown menus; here’s one method. 


(auto) 


Asm 
Mixed 


1) Point to the menu name. 


2) Press the left mouse button; do not release the button. Move the mouse 
down the menu until your choice is highlighted. 


3) Release the mouse button. 


For more information about the pulldown menus, refer to Section 4.2, Using 
the Pulldown Menus, on page 4-7. 


Pressing this key causes the debugger to switch modes in this order: 


(~ auto —H-W--+ assembly ———+ = 


Enter any of these commands to switch to the desired debugging mode: 


Changes from the current mode to auto mode. 
Changes from the current mode to assembly mode. 
Changes from the current mode to mixed mode. 


If the debugger is already in the desired mode when you enter a mode com- 
mand, then the command has no effect. 
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6.2 Displaying Your Source Programs (or Other Text Files) 


The debugger displays two types of code: 


[_] It displays assembly language code in the DISASSEMBLY window in 
auto, assembly, or mixed mode. 


[_] It displays C code in the FILE window in auto and mixed modes. 


The DISASSEMBLY and FILE windows are primarily intended for displaying 
code that the PC points to. By default, the FILE window displays the C source 
for the current function (if any), and the DISASSEMBLY window shows the cur- 
rent disassembly. 


Sometimes it’s useful to display other files or different parts of the same file; 
for example, you may wantto set a breakpoint at an undisplayed line. The DIS- 
ASSEMBLY and FILE windows are not large enough to show the entire con- 
tents of most assembly language and C files, but you can scroll through the 
windows. You can also tell the debugger to display specific portions of the dis- 
assembly or C source. 


Displaying assembly language code 


6-4 


The assembly language code in the DISASSEMBLY window is the reverse as- 
sembly of memory contents. (This code doesn’t come from any of your text 
files or from the intermediate assembly files produced by the compiler.) 


Q0001lc 6a07ffea 


000020 
000021 


addresses memory contents disassembly of object 
(object code) code in memory 


DISASS! LY- 1 
O001lc 6&07ffea BN main+7 (0xf£00007) 4 
Q0001ld 6a00ffEE BU main+29 (0xf0001d) 
00001le O0£f2b0000 call: PUSH AR3 

00001f 080b0014 LDI SP,AR3 

000020 6a000015 BU call+24 (0x£00036) 
000021 08400b02 LDI *-AR3 (2) ,RO 


dasm 


or 


addr 


or 
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When you invoke the debugger, it comes up in auto mode. If you load an object 
file when you invoke the debugger, then the DISASSEMBLY window displays 
the reverse assembly of the object file that’s loaded into memory. If you don’t 
load an object file, the DISASSEMBLY window shows the reverse assembly 
of whatever happens to be in memory. 


In assembly and mixed modes, you can use these commands to display a dif- 
ferent portion of code in the DISASSEMBLY window. 


Use the DASM command to display code beginning at a specific point. The 
syntax for this command is: 


dasm_ address 
dasm_ function name 


This command modifies the display so that address or function name is dis- 
played within the DISASSEMBLY window. The debugger continues to display 
this portion of the code until you run a program and halt it. 


Use the ADDR command to display assembly language code beginning at a 
specific point. The syntax for this command is: 


addr address 
addr function name 


In assembly mode, ADDR works like the DASM command, positioning the 
code starting at address or at function name as the first line of code in the DIS- 
ASSEMBLY window. In mixed mode, ADDR affects both the DISASSEMBLY 
and FILE windows. 


Modifying assembly language code 


<a 


You can modify the code in the disassembly window on a statement-by-state- 
ment basis. The method for doing this is called patch assembly. Patch assem- 
bly provides a simple way to temporarily correct minor problems by allowing 
you to change individual statements and instruction words. 


You can patch-assemble code by using a command or by using the mouse. 


Use the PATCH command to identify the address of the statement you want 
to change and the new statement you want to use at that address. The format 
for this command is: 


patch address, assembly language statement 
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6-6 


OK 


For patch assembly, use the right mouse button instead of the left. (Clicking 
the left mouse button sets a software breakpoint.) 


1) 


2) 


Point to the statement that you want to modify. 


Click the right button. The debugger will open a dialog box so that you can 
enter the new statement. The address field will already be filled in; clicking 
on the statement defines the address. The statement field will already be 
filled in with the current statement at that address (this is useful when only 
minor edits are necessary). 


Patch assembly may, at times, cause undesirable side effects: 


(_] Patching a multiple-word instruction with an instruction of lesser length will 


leave “garbage” or an unwanted new instruction in the remaining old 
instruction fragment. This fragment must be patched with either a valid 
instruction or a NOP, or else unpredictable results may occur when run- 
ning code. 


Substituting a larger instruction for a smaller one will partially or entirely 
overwrite the following instruction; you will lose the instruction and may be 
left with another fragment. 


If you want to insert a large amount of new code or if you want to skip over a 
section of code, you can use a different patch assembly technique: 


_] To insert a large section of new code, patch a branch instruction to go to 


an area of memory not currently in use. Using the patch assembler, add 
new code to this area of memory and branch back to the statement follow- 
ing the initial branch. 


To skip over a portion of code, patch a branch instruction to go beyond that 
section of code. 


The patch assembler changes only the disassembled assembly 
language code—it does not change your source code. After 
determining the correct solution to problems in the disassembly, edit 


your source file, recompile or reassemble it, and reload the new 
object file into the debugger. 
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Additional information about modifying assembly language code 


When using patch assembly to modify code in the disassembly window, keep 
these things in mind: 


LL} 
L} 


Directives. You cannot use directives (such as .global or .word). 


Expressions. You can use constants, but you cannot use arithmetic 
expressions. For example, an expression like 12 + 33 is not valid in patch 
assembly, but a constant such as 12 is allowed. 


Labels. You cannot define labels. For example, a statement such as the 
following is not allowed: 


LOOP: B LOOP 


However, an instruction can refer to a label, as long as it is defined ina 
COFF file that is already loaded. 


Constants. You can use hexadecimal, octal, decimal, and binary 
constants. The syntax to input constants is the same as that for the DSP 
assembler. (Refer to the TMS320 Floating-Point DSP Assembly 
Language Tools User’s Guide.) 


Parallel instructions. You can use parallel instructions. The syntax of 
these instructions is the same as that for the DSP assembler. (Refer to the 
TMS320 Floating-Point DSP Assembly Language Tools User’s Guide.) 


Error messages. The error messages for the patch assembler are the 
same as the corresponding DSP assembler error messages. Refer to the 
TMS320 Floating-Point DSP Assembly Language Tools User’s Guide for 
a detailed list of these messages. 
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Displaying C code 
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file 


func 


or 


Unlike assembly language code, C code isn’t reconstructed from memory con- 
tents—the C code that you view is your original C source. You can display C 
code explicitly or implicitly: 


[_.] You can force the debugger to show C source by entering a FILE, FUNC, 
or ADDR command. 


[_] In auto and mixed modes, the debugger automatically opens a FILE win- 
dow if you’re currently running C code. 


These commands are valid in C and mixed modes. 


Use the FILE command to display the contents of any text file. The syntax for 
this command is: 


file filename 


This uses the FILE window to display the contents of filename. The debugger 
continues to display this file until you run a program and halt in a C function. 
Although this command is most useful for viewing C code, you can use the 
FILE command for displaying any text file. You can view only one text file at 
atime. You can also access this command from the Load pulldown menu. 


(Note that displaying a file doesn’t load that file’s object code. If you want to 
be able to run the program, you must load the file’s associated object code as 
described in Section 6.3 on page 6-10.) 


Use the FUNC command to display a specific C function. The syntax for this 
command is: 


fune function name 
func address 


FUNC modifies the display so that function name or address is displayed with- 
in the window. If you supply an address instead of a function name, the FILE 
window displays the function containing address and places the cursor at that 
line. 


Note that FUNC works similarly to FILE, but you don’t need to identify the name 
of the file that contains the function. 


addr 


HW 


or 
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Use the ADDR command to display C code beginning at a specific point. The 
syntax for this command is: 


addr address 
addr function name 


In a C display, ADDR works like the FUNC command, positioning the code 
starting at address or at function name as the first line of code in the FILE win- 
dow. In mixed mode, ADDR affects both the FILE and DISASSEMBLY win- 
dows. 


Whenever the CALLS window is open, you can use the mouse or function keys 
to display a specific C function. This is similar to the FUNC or ADDR command 
but applies only to the functions listed in the CALLS window. 


1) Inthe CALLS window, point to the name of C function. 


2) Click the left mouse button. 


(If the CALLS window is active, you can also use the arrow keys and to 
display the function; see the CALLS window discussion on page 3-9 for de- 
tails.) 


Displaying other text files 


The DISASSEMBLY window always displays the reverse assembly of memory 
contents, no matter what is in memory. 


The FILE window is primarily for displaying C code, but you can use the FILE 
command to display any text file within the FILE window. You may, for example, 
wish to examine system files such as autoexec.bat or an initialization batch file. 
You can also view your original assembly language source files in the FILE 
window. 


You are restricted to displaying files that are 65,518 bytes long or less. 
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6.3 Loading Object Code 


In order to debug a program, you must load the program’s object code into 
memory. You can do this as you’re invoking the debugger, or you can do it after 
you've invoked the debugger. (Note that you create an object file by compiling, 
assembling, and linking your source files; see Section 1.4, Preparing Your Pro- 
gram for Debugging, on page 1-10.) 


Loading code while invoking the debugger 


You can load an object file when you invoke the debugger (this has the same 
effect as using the debugger’s LOAD command). To do this, enter the ap- 
propriate debugger-invocation command along with the name of the object 
file. 


If you want to load a file’s symbol table only, use the —s option (this has the 
same effect as using the debugger’s SLOAD command). To do this, enter the 
appropriate debugger-invocation command along with the name of the object 
file and specify —s. 


Loading code after invoking the debugger 


load 


reload 


sload 


After you invoke the debugger, you can use one of three commands to load 
object code and/or the symbol table associated with an object file. Use these 
commands as described below, or use them from the Load pulldown menu. 


Use the LOAD command to load both an object file and its associated symbol 
table. In effect, the LOAD command performs both a RELOAD and an SLOAD. 
The format for this command is: 


load object filename 
If you don’t supply an extension, the debugger will look for filename.out. 


Use the RELOAD command to load only an object file without loading its 
associated symbol table. This is useful for reloading a program when memory 
has been corrupted. The format for this command is: 


reload [object filename] 


If you enter the RELOAD command without specifying a filename, the debug- 
ger reloads the file that you loaded last. 


Use the SLOAD command to load only a symbol table. The format for this com- 
mand is: 


sload object filename 


SLOAD is useful in a debugging environment in which the debugger cannot, 
or need not, load the object code (for example, if the code is in ROM). SLOAD 
clears the existing symbol table before loading the new one but does not 
modify memory or set the program entry point. 
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6.4 Where the Debugger Looks for Source Files 


cd 


use 


Some commands (FILE, LOAD, RELOAD, and SLOAD) expect a filename as 
a parameter. If the filename includes path information, the debugger uses the 
file from the specified directory and does not search for the file in any other di- 
rectory. If you don’t supply path information, though, the debugger must 
search for the file. The debugger first looks for these files in the current directo- 
ry. You may, however, have your files in several different directories. 


(_] If you’re using LOAD, RELOAD, or SLOAD, you have only two choices for 
supplying the path information: 


Specify the path as part of the filename. 


Alternatively, you can use the CD command to change the current di- 
rectory from within the debugger. The format for this command is: 


cd_ directory name 


_] If you’re using the FILE command, you have several options: 


Within the DOS environment, you can name additional directories with 
the D_SRC environment variable. The format for doing this is: 


SET D_SRC=pathname;pathname 


This allows you to name several directories that the debugger can 
search. If you use the same directories often, it may be convenient to 
set the D_SRC environment variable in your autoexec.bat or in- 
itdb.bat file. If you do this, then the list of directories is always available 
when you're using the debugger. 


When you invoke the debugger, you can use the — i option to name 
additional source directories for the debugger to search. The format 
for this option is —i pathname. 


You can specify multiple pathnames by using several —i options (one 
pathname per option). The list of source directories that you create 
with —i options is valid until you quit the debugger. 


Within the debugger environment, you can use the USE command to 
name additional source directories. The format for this command is: 


use directory name 


You can specify only one directory at a time. 


In all cases, you can use relative pathnames such as ..\csource or ..\..\code. 
The debugger can recognize a cumulative total of 20 paths specified with 
D_SRC, -i, and USE. 
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6.5 Running Your Programs 


To debug your programs, you must execute them on one of the three 'C3x de- 
bugging tools (emulator, evaluation module, or simulator). The debugger pro- 
vides two basic types of commands to help you run your code: 


Basic run commands run your code on the target system without updat- 
ing the display until you explicitly halt execution. There are several ways 
to halt execution: 


@ Seta breakpoint. 

HM When you issue a run command, define a specific stopping point. 
HM Press so). 

M@ Press the left mouse button. 


Single-step commands execute assembly language or C code, one 
statement at time, and update the display after each execution. 


Defining the starting point for program execution 


rest 


?/eval 


All run and single-step commands begin executing from the current PC (pro- 
gram counter). When you load an object file, the PC is automatically set to the 
starting point for program execution. You can easily identify the current PC by: 


LJ 


LJ 


or 


Finding its entry in the CPU window 

or 

Finding the appropriately highlighted line in the FILE or DISASSEMBLY 
window. To do this, execute one of these commands: 


dasm PC 
addr PC 


Sometimes you may want to modify the PC to point to a different position in 
your program. There are two ways to do this: 


O 


or 


| 


or 


If you executed some code and would like to rerun the program from the 
original program entry point, use the RESTART (REST) command. The 
format for this command is: 


restart 
rest 


Note that you can also access this command from the Load pulldown 
menu. 


You can directly modify the PC’s contents with one of these commands: 


2PC=new value 
eval pc = new value 


After halting execution, you can continue from the current PC by reissuing any 
of the run or single-step commands. 


Running code 


L run 
Ss 


go 


ret 


or 


runb 


Running Your Programs 


The debugger supports several run commands. 


The RUN command is the basic command for running an entire program. The 
format for this command is: 


run [expression] 
The command's behavior depends on the type of parameter you supply: 


_] Ifyou don’t supply an expression, the program executes until it encounters 
a breakpoint or until you press or the left mouse button. 


_] If you supply a logical or relational expression, this becomes a conditional 
run (see page 6-17). 


|_| If you supply any other type of expression, the debugger treats the expres- 
sion as a count parameter. The debugger executes count instructions, 
halts, then updates the display. 


Use the GO command to execute code up to a specific point in your program. 
The format for this command is: 

go_ [address] 

If you don’t supply an address parameter, then GO acts like a RUN command 
without an expression parameter. 

The RETURN (RET) command executes the code in the current C function 
and halts when execution returns to its caller. The format for this command is: 


return 
ret 


Breakpoints do not affect this command, but you can halt execution by press- 
ing or the left mouse button. 


Use the RUNB (run benchmark) command to execute a specific section of 
code and count the number of clock cycles consumed by the execution. The 
format for this command is: 


runb 


Using the RUNB command to benchmark code is a multistep process, de- 
scribed in Section 6.7, Benchmarking, on page 6-19. 


Pressing this key runs code from the current PC. This is similar to entering a 
RUN command without an expression parameter. 
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Single-stepping through code 


step 


Single-step execution is similar to running a program that has a breakpoint set 
on each line. The debugger executes one statement, updates the display, and 
halts execution. (You can supply a parameter that tells the debugger to single- 
step more than one statement; the debugger updates the display after each 
statement.) You can single-step through assembly language code or C code. 


The debugger supports several commands for single-stepping through a pro- 
gram. Command execution may vary, depending on whether you’re single- 
stepping through C code or assembly language code. 


ce, 
Note: 


The single-stepping debugger commands (STEP, CSTEP, and NEXT) turn 
off the global interrupt bit GIE and prevent stepping through an interrupt ser- 
vice routine. If you want to step into an interrupt service routine, set a break- 
point in the interrupt service routine and use one of the run commands. 


Each of the single-step commands has an optional expression parameter that 
works like this: 


[__] If you don’t supply an expression, the program executes a single state- 
ment, then halts. 


__] If you supply a logical or relational expression, this becomes a conditional 
single-step execution (see page 6-17). 


|_| If you supply any other type of expression, the debugger treats the expres- 
sion as a countparameter. The debugger single-steps count C or assem- 
bly language statements (depending on the type of code you're in). 


Use the STEP command to single-step through assembly language or C code. 
The format for this command is: 


step [expression] 


If you’re in C code, the debugger executes one C statement at a time. In as- 
sembly or mixed mode, the debugger executes one assembly language state- 
ment at a time. 


If you’re single-stepping through C code and encounter a function call, the 
STEP command shows you the single-step execution of the called function 
(assuming that the function was compiled with the compiler’s —g debug 
option). When function execution completes, single-step execution returns to 
the caller. If the function wasn’t compiled with the debug option, the debugger 
executes the function but doesn’t show single-step execution of the function. 


cstep 


next 
cnext 


Running Your Programs 


The CSTEP command is similar to STEP, but CSTEP always single-steps in 
terms of a C statement. If you’re in C code, STEP and CSTEP behave identi- 
cally. In assembly language code, however, CSTEP executes all assembly 
language statements associated with one C statement before updating the 
display. The format for this command is: 


cstep [expression| 


The NEXT and CNEXT commands are similar to the STEP and CSTEP com- 
mands. The only difference is that NEXT/CNEXT never show single-step 
execution of called functions—they always step to the next consecutive state- 
ment. The formats for these commands are: 


next [expression] 
cnext [expression] 


You can also single-step through programs by using function keys. 


Acts as a STEP command. 


Acts as a NEXT command. 


The debugger allows you to execute several single-step commands from the 
selections on the menu bar. 


To execute a STEP: 


1) Point to Step=F8 in the menu bar. 


2) Press and release the left mouse button. 


To execute a NEXT: 


1) Point to Next=F10 in the menu bar. 


2) Press and release the left mouse button. 
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Running code while disconnected from the target 


runf 
EVM & 
emulator 
halt 
reset 


Use the RUNF command to disconnect the emulator or EVM from the target 
system while code is executing. The format for this command is: 


runf 


When you enter RUNF, the debugger clears all breakpoints, disconnects the 
emulator or EVM from the target system, and causes the processor to begin 
execution at the current PC. You can quit the debugger, or you can continue 
to enter commands. However, any command that causes the debugger to ac- 
cess the target at this time will produce an error. 


RUNMF is useful in a multiprocessor system. It’s also useful ina system in which 
several target systems share an emulator; RUNF enables you to disconnect 
the emulator from one system and connect it to another. 


Use the HALT command to halt the target system after you’ve entered a RUNF 
command. The format for this command is: 


halt 


When you invoke the debugger, it automatically executes a HALT command. 
Thus, if you enter a RUNF, quit the debugger, and later reinvoke the debugger, 
you will effectively reconnect the emulator to the target system and run the de- 
bugger in its normal mode of operation. When you invoke the debugger, use 
the —s option to preserve the current PC and memory contents. 


The RESET command resets the target system. This is a software reset. The 
format for this command is: 


reset 


If you are using the simulator and execute the RESET commana, the simulator 
simulates the ’C3x processor and peripheral reset operation, putting the pro- 
cessor in a known state. 


Running Your Programs 


Running code conditionally 


The RUN, STEP, CSTEP, NEXT, and CNEXT commands all have an optional 
expression parameter that can be a relational or logical expression. This type 
of expression has one of the following operators as the highest precedence 
operator in the expression: 


Vv 
— il Vv 
ll 


When you use this type of expression with these commands, the command 
becomes a conditional run. The debugger executes the command repeatedly 
for as long as the expression evaluates to true. 


You must use software breakpoints with conditional runs; the expression is 
evaluated each time the debugger encounters a breakpoint. Each time the de- 
bugger evaluates the conditional expression, it updates the screen. The de- 
bugger applies this algorithm: 


top: 
if (expression = = 0), go to end; 
run or single-step (until breakpoint, ESC) , or mouse button halts execution) 
if (halted by breakpoint, not by or mouse button), go to top 

end: 


Generally, you should set the breakpoints on statements that are related in 
some way to the expression. For example, if you’re watching a particular vari- 
able in a WATCH window, you may want to set breakpoints on statements that 
affect that variable and use that variable in the expression. 
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6.6 Halting Program Execution 


ESC 


Whenever you’re running or single-stepping code, program execution halts 
automatically if the debugger encounters a breakpoint or if it reaches a particu- 
lar point where you told it to stop (by supplying a countor an address). If you'd 
like to explicitly halt program execution, there are two ways to accomplish this: 


Click the left mouse button. 


Press the escape key. 


After halting execution, you can continue program execution from the current 
PC by reissuing any of the run or single-step commands. 


6.7 Benchmarking 


Benchmarking 


The debugger allows you to keep track of the number of CPU clock cycles con- 
sumed by a particular section of code. The debugger maintains the count in 
a pseudoregister named CLK. 


Benchmarking code is a multiple-step process: 


Step 1: 


Step 2: 


Step 3: 
Step 4: 


Set a software breakpoint at the statement that marks the beginning 
of the section of code you'd like to benchmark. 


Set a software breakpoint at the statement that marks the end of the 
section of code you'd like to benchmark. 


Enter any RUN command to execute code up to the first breakpoint. 


Now enter the RUNB command: 
runb 


When the processor halts at the second breakpoint, the value of CLK is valid. 
To display it, use the ? command or enter it into the WATCH window with the 
WA command. This value is valid until you enter another RUN command. 


Note: 


[_] The RUNB command counts CPU clock cycles from the current PC to 
the breakpoint. This count is not cumulative. You cannot add the number 
of clock cycles from point A to point B to the number of cycles from point 
B to point C to learn the number of cycles from point A to point C. This 
error occurs because of pipeline filling and flushing. 


(_] The value in CLK is valid only after using a RUNB command thatis termi- 
nated by a software breakpoint. 
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Chapter 7 


Managing Data 


The debugger allows you to examine and modify many different types of data 
related to the ’C3x and to your program. You can display and modify the values 
of: 

[_] Individual memory locations or a range of memory 

__] 'C3x registers 

[__] Variables, including scalar types (ints, chars, etc.) and aggregate types 

(arrays, structures, etc.) 

Topic Page 
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7.2._Basic Commands for Managing Data 7-2 
7.3. Basic Methods for Changing Data Values 7-4 

Editing data displayed in a window 7-4 
Advanced “editing’—using expressions with side effects 7-5 
7.4 Managing Data in Memory 7-6 
Displaying memory contents 7-6 
Displaying memory contents while you’re debugging C 7-8 
Saving memory values to a file 7-9 
Filling a block of memory 7-9 
7.5 Managing Register Data 7-10 
Displaying register contents 7-10 
Accessing extended-precision registers 7-11 
7.6 Managing Data in a DISP (Display) Window 7-12 
Displaying data in a DISP window TAVE 
Closing a DISP window 7-14 
7.7 Managing Data in a WATCH Window 7-14 
Displaying data in a WATCH window TAS 
Deleting watched values and closing the WATCH window 7-16 
7.8 Monitoring the Pipeline (Simulator Only) 7-17 
7.9 Displaying Data in Alternative Formats 7-18 
Changing the default format for specific data types 7-18 
Changing the default format with ?, MEM, DISP, and WA 7-20 


Where Data is Displayed / Basic Commands for Managing Data 


7.1. Where Data Is Displayed 


Four windows are dedicated to displaying the various types of data. 


Type of data Window name and purpose 
memory locations MEMORY windows 
Display the contents of a range of 
memory 
register values CPU window 


Displays the contents of ’C3x registers 
pointer data or selected variables of | DISP windows 


an aggregate type Display the contents of aggregate types 
and show the values of individual 
members 

selected variables (scalar types or WATCH window 

individual members of aggregate Displays selected data 


types) and specific memory loca- 
tions or registers 


This group of windows is referred to as data-display windows. 


7.2 Basic Commands for Managing Data 


The debugger provides special-purpose commands for displaying and modify- 
ing data in dedicated windows. The debugger also supports several general- 
purpose commands that you can use to display or modify any type of data. 


~@ whatis If you want to know the type of a variable, use the WHATIS command. The syn- 
a tax for this command is: 


whatis symbol 


This lists symbol! data type in the COMMAND window display area. The sym- 
bolcan be any variable (local, global, or static), a function name, structure tag, 
typedef name, or enumeration constant. 


Command Result displayed in the COMMAND window 
whatis giant struct zzz giant[100]; 
whatis xxx struct xxx { 

int a; 

int b; 

Int: 167 

int fl: 2; 

int £2 : 4; 


iv 
struct xxx *£3; 
int £4[10]; 
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eval 


or 
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The ? (evaluate expression) command evaluates an expression and shows 
the result in the COMMAND window display area. The basic syntax for this 
command is: 


2 expression 


The expression can be any C expression, including an expression with side 
effects. However, you cannot use a string constant or function call in the ex- 
pression. 


If the result of expression is scalar, then the debugger displays the result as 
a decimal value in the COMMAND window. If expressionis a structure or array, 
? displays the entire contents of the structure or array; youcan halt long listings 
by pressing (Esc). 


Here are some examples that use the ? command: 


Command Result displayed in the COMMAND window 


? giant giant [0].b1 436547877 
giant [0].b2 -—791051538 
giant [0].b3 1952557575 
giant [0].b4 -1555212096 


etc. 
oe | 4194425 
? j=0x5a 90 
? i -12635 
dae Wee 4 0x000cea5 


Note that the DISP command (described in detail on page 7-12) behaves like 
the ? command when its expression parameter does not identify an aggregate 


type. 


The EVAL (evaluate expression) command behaves like the ? command but 
does not show the result in the COMMAND window display area. The syntax 
for this command is: 


eval expression 
e expression 


EVAL is useful for assigning values to registers or memory locations in a batch 
file (where it’s not necessary to display the result). 
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7.3 Basic Methods for Changing Data Values 


The debugger provides you with a great deal of flexibility in modifying various 
types of data. You can use the debugger’s overwrite editing capability, which 
allows you to change a value simply by typing over its displayed value. You can 
also use the data-management commands for more complex editing. 


Editing data displayed in a window 


ESC 
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Use overwrite editing to modify data in a data-display window; you can edit: 


__] Registers displayed in the CPU window 

[_] Memory contents displayed ina MEMORY window 
[_] Elements displayed in a DISP window 

[_| Values displayed in the WATCH window 


There are two similar methods for overwriting displayed data: 


This method is sometimes referred to as the “click and type” method. 


1) Point to the data item that you want to modify. 


2) Click the left button. The debugger highlights the selected field. (Note that 
the window containing this field becomes active when you press the 
mouse button.) 


3) Type the new information. If you make a mistake or change your mind, 
press or move the mouse outside the field and press/release the left 
button; this resets the field to its original value. 


4) When you finish typing the new information, press or any arrow key. 
This replaces the original value with the new value. 


1) Select the window that contains the field you’d like to modify; make this the 
active window. (Use the mouse, the WIN command, or . For more de- 
tail, see Section 3.4, The Active Window, on page 3-19.) 


2) Use arrow keys to move the cursor to the field you'd like to edit. 
Moves up 1 field at a time. 

Moves down 1 field at a time. 

Moves left 1 field at a time. 


UNHBB 


Moves right 1 field at a time. 
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(F9) 3) When the field you’d like to edit is highlighted, press 3). The debugger 
highlights the field that the cursor is pointing to. 


ESC 4) Type the new information. If you make a mistake or change your mind, 
press (Esc) ; this resets the field to its original value. 


e) 5) When you finish typing the new information, press or any arrow key. 
This replaces the original value with the new value. 


Advanced “editing”—using expressions with side effects 


Using the overwrite editing feature to modify data is straightforward. However, 
there are additional data-management methods that take advantage of the 
fact that C expressions are accepted as parameters by most debugger com- 
mands, and that C expressions can have side effects. When an expression 
has a side effect, it means that the value of some variable in the expression 
changes as the result of evaluating the expression. 


This means that you can coerce many commands into changing values for 
you. Specifically, it’s most helpful to use ? and EVAL to change data as well 
as display it. 

For example, if you want to see what’s in register R83, you can enter: 

? R3 


However, you can also use this type of command to modify R3’s contents. 
Here are some examples of how you might do this: 


? R3++ Side effect: increments the contents of R3 by 1 
eval --R3 Side effect: decrements the contents of R3 by 1 
? R3 = 8 Side effect: sets R3 to 8 
eval R3/=2 Side effect: divides contents of R3 by 2 


Note that not all expressions have side effects. For example, if you enter 
2? R3+4, the debugger displays the result of adding 4 to the contents of R3 but 
does not modify R3’s contents. Expressions that have side effects must con- 
tain an assignment operator or an operator that implies an assignment. Opera- 
tors that can cause a side effect are: 


= += -_—= *e /= 
%= &= Ax = <<c= 
>>= ++ == 
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7.4 Managing Data in Memory 


In mixed and assembly modes, the debugger maintains a MEMORY window 
that displays the contents of memory. For details concerning the MEMORY 
window, see the MEMORY windows discussion (page 3-12). 


-—— MEMORY 


000000 
000005 
00000a 
OO0000£ 
000014 
000019 


0000 
00000043 
00000047 
00000000 
00000000 
00000000 


00000040 
00 
00000048 
00000000 
00000000 
00000000 


00000041 00000042 
00000046 
O4a 
00000000 data 
00000000 


00000000 


000 
00000000 


addresses 00000000 


The debugger has commands that show the data values at a specific location 
or that display a different range of memory in the MEMORY window. The de- 
bugger allows you to change the values at individual locations; refer to Section 
7.3 (page 7-4), for more information. 


Displaying memory contents 
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The main way to observe memory contents is to view the display in a 
MEMORY window. Four MEMORY windows are available: the default window 
is labeled MEMORY, and the three additional windows are called MEMORY 1, 
MEMORY2, and MEMORY3S. Notice that the default window does not have an 
extension number in its name; this is because MEMORY1, MEMORY2, and 
MEMORY$3 are pop-up windows that can be opened and closed throughout 
your debugging session. Having four windows allows you to view four different 
memory ranges. 


The amount of memory that you can display is limited by the size of the individ- 
ual MEMORY windows (which is limited only by the screen size). During a de- 
bugging session, you may need to display different areas of memory within a 
window. You can do this by typing a command or using the mouse. 
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If you want to display a different memory range in the MEMORY window, use 


L mem 
eS 


the MEM command. You can do this by entering: 
mem expression 


To view different memory locations in an additional MEMORY window, use the 
MEM command with the appropriate extension number. For example: 


To do this... Enter this. . . 


View the block of memory starting at address Ox8000 mem1 0x8000 
in the MEMORY1 window 


View the same block of memory (starting at address mem2 0x8000 
0x8000) but in the MEMORY2 window 


Note: 


If you want to view a different block of memory explicitly in the default 
MEMORY window, you can use the aliased command MEMO. This works ex- 
actly the same as the MEM command. To use this command, enter: 
mem0 address 


| ss) 
For more information, see the MEMORY windows discussion on page 3-12. 


The expression you type in represents the address of the first entry in the 
MEMORY window. The end of the range is defined by the size of the window: 
to show more memory locations, make the window larger; to show fewer loca- 
tions, make the window smaller. (See Resizing a window, page 3-21, for more 
information.) 


Expressioncan be an absolute address, a symbolic address, or any C expres- 
sion. Here are several examples: 


(_] Absolute address. Suppose that you want to display memory, beginning 
from the very first address. You might enter this command: 
mem 0x00 


Hint: MEMORY window addresses are shown in hexadecimal format. If 
you want to specify a hex address, be sure to prefix the address number 
with 0x; otherwise, the debugger treats the number as a decimal address. 


[_} Symbolic address. You can use any defined C symbol. For example, if 
your program defined a symbol named SYM, you could enter this com- 
mand: 


mem &SYM 


Hint: Prefix the symbol with the & operator to use the address of the sym- 
bol. 
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[_} C expression. If you use a C expression as a parameter, the debugger 
evaluates the expression and uses the result as a memory address: 


mem SP — RO + label 


You can also change the display of any data-display window— including the 
MEMORY window—by scrolling through the window’s contents. See the 
Scrolling through a window's contents discussion (page 3-26) for more details. 


Displaying memory contents while you’re debugging C 
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If you’re debugging C code in auto mode, you won’t see a MEMORY window— 
the debugger doesn’t show the MEMORY window in the C-only display. How- 
ever, there are several ways to display memory in this situation. 


Hint: If you want to use the contents of an address as a parameter, be sure 
to prefix the address with the C indirection operator (*). 


(_] If you have only a temporary interest in the contents of a specific memory 
location, you can use the ? command to display the value at this address. 
For example, if you want to know the contents of memory location 26 
(hex), you could enter: 


? *0x26 
The debugger displays the memory value in the COMMAND window dis- 
play area. 


(_] If you want the opportunity to observe a specific memory location over a 
longer period of time, you can display it ina WATCH window. Use the WA 
command to do this: 


wa *0x26 
[_} You can also use the DISP command to display memory contents. The 
DISP window shows memory in an array format with the specified address 


as “member” [0]. In this situation, you can also use casting to display 
memory contents in a different numeric format: 


disp *(float *) 0x26 
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Saving memory values to a file 


L ms 
<4 


Sometimes it’s useful to save a block of memory values to a file. You can use 
the MS (memory save) command to do this; the files are saved in COFF for- 
mat. The syntax for the MS command is: 


ms_ address, length, filename 
[_] The address parameter identifies the first address in the block. 


[|_| The length parameter defines the length, in words, of the block. This pa- 
rameter can be any C expression. 


[__] The filename is a system file. If you don’t supply an extension, the debug- 
ger adds an .obj extension. 


For example, to save the values in data memory locations 0x0—0x10 to a file 
named memsave, you could enter: 


ms 0x0,0x10,memsave 


To reload memory values that were saved in a file, use the LOAD command. 
For example, to reload the values that were stored in memsave, enter: 


load memsave.obj 


Filling a block of memory 


i 


Sometimes it’s useful to be able to fill an entire block of memory at once. You 
can do this by using the FILL command. The syntax for this command is: 


fill address, length, data 


[| The address parameter identifies the first address in the block. 
[|_| The length parameter defines the number of words to fill. 
[|_| The data parameter is the value that is placed in each word in the block. 


For example, to fill locations 0x0080 0000 to 0x0080 0300 with the value 
0x1234 ABCD, you would enter: 


fill 0x800000,0x301,0x1234abcd 


If you want to check to see that memory has been filled correctly, you can enter: 
mem 0x800000 


This changes the MEMORY window display to show the block of memory be- 
ginning at address 0x0080 0000. 


Note that the FILL command can also be executed from the Memory pulldown 
menu. 


Managing Data 7-9 


Managing Register Data 


7.5 Managing Register Data 


In mixed and assembly modes, the debugger maintains a CPU window that 
displays the contents of individual registers. For details concerning the CPU 
window, see the CPU window discussion (page 3-15). 


CPU 1 


: Pc 00£00076 sp 00000755 4 
register 00000003 R1 00000005 
name 00000007. +R3 00000000 

R4 00 00 R5 00000000 
R6 00000000 00000000 


ARO 00001802 AR1 00000000 
AR2 00000000 AR3 00090000 
AR4 00000000 00000000 
AR7 00000000 
IR1 00000000 
00000000 RC 00000000 
000 RE 00000000 


DP 00000000 BK 00000000 
IE 00000000 IF 00000000 | 


register 
contents 


The debugger provides commands that allow you to display and modify the 
contents of specific registers. Remember, you can use the data-management 
commands or the debugger’s overwrite editing capability to modify the con- 
tents of any register displayed in the CPU or WATCH window. Refer to Section 
7.3, Basic Methods for Changing Data Values (page 7-4), for more informa- 
tion. 


Displaying register contents 
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The main way to observe register contents is to view the display in the CPU 
window. However, you may not be interested in all of the registers—if you’re 
interested in only two registers, you might want to make the CPU window small 
and use the extra screen space for the DISASSEMBLY or FILE display. In this 
type of situation, there are several ways to observe the contents of the selected 
registers. 


_] If you have only atemporary interest in the contents of a register, you can 
use the ? command to display the register’s contents. For example, if you 
want to know the contents of the SP, you could enter: 


? SP & 


The debugger displays the SP’s current contents in the COMMAND win- 
dow display area. 
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_] If you want to observe a register over a longer period of time, you can use 
the WA command to display it ina WATCH window. For example, if you 
want to observe the status register, you could enter: 


wa ST,Status Reg 


This adds the ST to the WATCH window and labels it as Status Reg. The 
register’s contents are continuously updated, just as if you were observing 
the register in the CPU window. 


When you’re debugging C in auto mode, these methods are also useful be- 
cause the debugger doesn’t show the CPU window in the C-only display. 
Accessing extended-precision registers 


The simulator represents extended-precision registers in the register file with 
a set of registers, Enand Rn. The nrepresents the register number. The regis- 
ter ranges are: 


Range Description 
EO-E7 Represent the exponent of the floating-point number. 
RO-R7 Represent the mantissa of the floating-point number or a 32-bit integer. 


For example, if you loaded the 40-bit floating-point number 0x0003 4000 0000 
into extended-precision register R1, the simulator will load it as: 


El 
R1 


03h (exponent) 
40000000h (mantissa) 


Register E1 is essentially a pseudoregister provided by the simulator. Float- 
ing-point instructions affect both the exponent and mantissa fields (Rn and 
En), but inters instructions affect only the mantissa field (Rn). 


The CPU window displays all of the registers in the primary register and expan- 
sion register files; however, the display window displays only the mantissa 
(Rn) portion of the register in the extended-precision register file. To display 
the exponent (En) portion, either use the EVAL command, or add the exponent 
portion to the WATCH window. 
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7.6 Managing Data in a DISP (Display) Window 


The main purpose of the DISP window is to display the values of members of 
complex, aggregate data types such as arrays and structures. The debugger 
shows DISP windows only when you specifically request to see DISP windows 
with the DISP command (described below). Note that you can have up to 120 
DISP windows open at once. For additional details about DISP windows, see 
the DISP window discussion (page 3-16). 


;-DISP: str ——W—Y__, 


a 84 A 
b 86 
structure ——-= 455 
members £1 —DISP: str.£4 ———_, 
£27° 7 [0] 44276127 A 
v [1] 1778712578 
£3  0x18740001 
member A fleuet [2] 555492660 


values [3] 356713217 
ee 138412802 
[5] 182452229 
[6] 35659888 
This member is an array, and [7] 37749506 
you can display its contents in [8] 134742016 i 
a second DISP window [9] 138412801 d 


Remember, you can use the data-management commands or the debugger’s 
overwrite editing capability to modify the contents of any value displayed in a 
DISP window. Refer to Section 7.3, Basic Methods for Changing Data Values 
(page 7-4), for more information. 


Displaying data in a DISP window 
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To open a DISP window, use the DISP command. The basic syntax is: 
disp expression 


If the expression is not an array, structure, or pointer (of the form “pointer 
name), the DISP command behaves like the ? command. However, if expres- 
sion is one of these types, the debugger opens a DISP window to display the 
values of the members. 


If a DISP window contains a long list of members, you can use (PAGEDOWN), 
, or arrow keys to scroll through the window. If the window contains an 
array of structures, you Can USe@ (CONTROL) (PAGE DOWN) and to 
scroll through the array. 
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Once you open a DISP window, you may find that a displayed member is 
another one of these types. This is how you identify the members that are ar- 
rays, structures, or pointers: 


A member that is an array looks like this: [ad 
A member that is a structure looks like this: {...} 
A member that is a pointer looks like an address: 0x00000000 


You can display the additional data (the data pointed to or the members of the 
array or structure) in additional DISP windows (these are referred to as chil- 
dren). There are three ways to do this. 


Use the DISP command again; this time, expression must identify the member 
that has additional data. For example, if the first expression identifies a struc- 
ture named strand one of str’s members is an array named 4, you can display 
the contents of the array by entering this command: 


disp str.f4 


This opens a new DISP window that shows the contents of the array. If str has 
a member named 73 that is a pointer, you could enter: 


disp *str.£3 


This opens a window to display what str.f3 points to. 


Here’s another method of displaying the additional data: 


1) Point to the member in the DISP window. 


2) Now click the left button. 


Here’s the third method: 
1) Usethe arrow keys to move the cursor up and down in the list of members. 


2) When the cursor is on the desired field, press (3). 


When the debugger opens a second DISP window, the new window may at 
first be displayed on top of the original DISP window; if so, you can move the 
windows so that you can see both at once. If the new windows also have mem- 
bers that are pointers or aggregate types, you can continue to open new DISP 
windows. 
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Closing a DISP window 


Closing a DISP window is a simple, two-step process. 


Step 1: Make the DISP window that you want to close active (see Section 
3.4, The Active Window, on page 3-19). 


Step 2: Press G4). 


Note that you can close a window and all of its children by closing the original 
window. 


| 


Note: 


The debugger automatically closes any DISP windows when you execute a 
LOAD or SLOAD command. 


sss | 


7.7 Managing Data in a WATCH Window 
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The debugger doesn’t maintain a dedicated window that tells you about the 
status of all the symbols defined in your program. Such a window might be so 
large that it wouldn’t be useful. Instead, the debugger allows you to create a 
WATCH window that shows you how program execution affects specific ex- 
pressions, variables, registers, or memory locations. 


WATCH 
watch index————"_{$1:__ aro.— so x00001802 
ZAR X+X 4 


' 
Vv 
Sp uv was | 


label current value 


The debugger displays a WATCH window only when you specifically request 
a WATCH window with the WA command (described below). Note that there 
is only one WATCH window. For additional details concerning the WATCH win- 
dow, see the WATCH window discussion (page 3-17). 


Managing Data in a WATCH Window 


Remember, you can use the data-management commands or the debugger’s 
overwrite editing capability to modify the contents of any value displayed in the 
WATCH window. Refer to Section 7.3, Basic Methods for Changing Data Val- 
ues (page 7-4), for more information. 
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Note: 


All of the watch commands described can also be accessed Watch 
from the Watch pulldown menu. For more information about on 
using the the pulldown menus, refer to Section 4.2, Using the cee 


Menu Bar and the Pulldown Menus (page 4-7). 
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Displaying data in the WATCH window 


me 
<a 


The debugger has one command for adding items to the WATCH window. 


To open the WATCH window, use the WA (watch add) command. The basic 
syntax is: 


wa_ expression |, label] 


When you first execute WA, the debugger opens the WATCH window. After 
that, executing WA adds additional values to the WATCH window. 


[_} The expression parameter can be any C expression, including an expres- 
sion that has side effects. It’s most useful to watch an expression whose 
value will change over time; constant expressions provide no useful func- 
tion in the watch window. 


(_] If you want to use the contents of an address as a parameter, be sure to 
prefix the address with the C indirection operator (*). Use the WA com- 
mand to do this: 


wa *0x26 


_] The /abe/ parameter is optional. When used, it provides a label for the 
watched entry. If you don’t use a /abel, the debugger displays the expres- 
sion in the label field. 
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Deleting watched values and closing the WATCH window 
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wd 


The debugger supports two commands for deleting items from the WATCH 
window. 


If you'd like to close the WATCH window and delete all of the items in a single 
step, use the WR (watch reset) command. The syntax is: 


wr 


If you'd like to delete a specific item from the WATCH window, use the WD 
(watch delete) command. The syntax is: 


wd_ index number 


Whenever you add an item to the WATCH window, the debugger assigns it an 
index number. (The illustration of the WATCH window on page 7-14 points to 
these watch indexes.) The WD command's index numberparameter must cor- 
respond to one of the watch indexes in the WATCH window. 


Note that deleting an item (depending on where it is in the list) causes the re- 
maining index numbers to be reassigned. Deleting the last remaining item in 
the WATCH window closes the WATCH window. 


a | 
Note: 


The debugger automatically closes the WATCH window when you execute 
a LOAD or SLOAD command. 
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7.8 Monitoring the Pipeline (Simulator Only) 


The simulator allows you to monitor the pipeline through pseudoregisters that 
you can query with ? or DISP or add to the WATCH window. 


The instruction pipeline consists of four phases: instruction fetch, decode, op- 
erand fetch, and execution. During any cycle, one to four instructions can be 
active, each at a different stage of completion. Instruction operation occurs 
during the appropriate stages of the pipeline. For example, the instruction ARn 
(n=0—7) updates of auxiliary registers occur during the decode phase. 


The simulator provides eight pseudoregisters that display the opcode or ad- 
dress of the instructions in each phase of the pipeline. The following table iden- 
tifies these registers. 


Table 7—1. Pipeline Pseudoregisters 


Pipeline phase Opcode pseudoregister Address pseudoregister 
Instruction fetch fins faddr 
Decode dins daddr 
Operand fetch rins raddr 
Execution xins xaddr 


For example, if you wanted to observe the decode phase during program 
execution, you could watch the dins and daddr pseudoregisters in the WATCH 
window: 


wa dins, Decode-Opcode 
wa daddr,Decode-Address 


This adds dins and dadadr to the WATCH window and labels them as Decode- 
Opcode and Decode-Address, respectively. 
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7.9 Displaying Data in Alternative Formats 


By default, all data is displayed in its natural format. This means that: 


[_] Integer values are displayed as decimal numbers. 

[_] Floating-point values are displayed in floating-point format. 

[|_| Pointers are displayed as hexadecimal addresses (with a Ox prefix). 
[_] Enumerated types are displayed symbolically. 


However, any data displayed in the COMMAND, MEMORY, WATCH, or DISP 
window can be displayed in a variety of formats. 
Changing the default format for specific data types 


To display specific types of data in a different format, use the SETF command. 
The syntax for this command is: 


setf [data type, display format | 


The display format parameter identifies the new display format for any data of 
type data type. Table 7-2 lists the available formats and the corresponding 
characters that can be used as the display format parameter. 


Table 7-2. Display Formats for Debugger Data 


Display Format Parameter Display Format Parameter 
Default for the data type i Octal oO 
ASCII character (bytes) c Valid address p 
Decimal d ASCII string s 
Exponential floating point e Unsigned decimal u 
Decimal floating point f Hexadecimal x 


Table 7-3 lists the C data types that can be used for the data type parameter. 
Only a subset of the display formats applies to each data type, so Table 7-3 
also shows valid combinations of data types and display formats. 
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Table 7—3. Data Types for Displaying Debugger Data 


Valid Display Formats 


Data Type c do x ef p su Default Display Format 
char Vv vVvov V ASCIl (c) 

uchar V vVviov V Decimal (d) 

short Vvvv V Decimal (d) 

int Vvv 4 V Decimal (d) 

uint vVvv Vv V Decimal (d) 

long VvVv 4 V Decimal (d) 

ulong VvVv Vv Vv Decimal (d) 

float Vv Exponential floating point (e) 
double Vv Exponential floating point (e) 
ptr Vv Vv Address (p) 


Here are some examples: 


[__] To display all data of type short as unsigned decimals, enter: 
setf short, u 


[__] To return all data of type short to its default display format, enter: 
setf short, * 


[_] To list the current display formats for each data type, enter the SETF com- 
mand with no parameters: 


setf 


You'll see a display that looks something like this: 


( Display Format Defaults 
Type char: ASCII 
Type unsigned char: Decimal 
Type int: Decimal 
Type unsigned int: Decimal 
Type short: Decimal 
Type unsigned short: Decimal 
Type long: Decimal 
Type unsigned long: Decimal 
Type float: Exponential floating point 
Type double: Exponential floating point 
Type pointer: Address 


[_] To reset all data types back to their default display formats, enter: 
setf * 
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Changing the default format with ?, MEM, DISP, and WA 
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You can also use the ?, MEM, DISP, and WA commands to show data in alter- 
native display formats. (The ? and DISP commands can use alternative for- 
mats only for scalar types, arrays of scalar types, and individual members of 
aggregate types.) 


Each of these commands has an optional display format parameter that works 
in the same way as the display format parameter of the SETF command. 


When you don’t use a display format parameter, data is shown in its natural 
format (unless you have changed the format for the data type with SETF). 


Here are some examples: 


[_} To watch the PC in decimal, enter: 
wa pce,,d 


_] To display memory contents in octal, enter: 
mem 0x0,0 


(_] To display an array of integers as characters, enter: 
disp ai,c 


The valid combinations of data types and display formats listed for SETF also 
apply to the data displayed with DISP, ?, WA, and MEM. For example, if you 
want to use display format e or f, the data that you are displaying must be of 
type float or type double. Additionally, you cannot use the s display format pa- 
rameter with the MEM command. 
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Using Software Breakpoints 


During the debugging process, you may want to halt execution temporarily so 
that you can examine the contents of selected variables, registers, and 
memory locations before continuing with program execution. You can do this 
by setting software breakpoints at critical points in your code. You can set 
software breakpoints in assembly language code and in C code. A software 
breakpoint halts any program execution, whether you’re running or single- 
stepping through code. 


Software breakpoints are especially useful in combination with conditional 
execution (described on page 6-17) and benchmarking (described on page 
6-19). 


Topic Page 
8.1 Setting a Software Breakpoint 8-2 
8.2 Clearing a Software Breakpoint 8-4 
8.3 Finding the Software Breakpoints That Are Set 8-5 
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8.1 Setting a Software Breakpoint 


When you set a software breakpoint, the debugger highlights the breakpointed 
line in two ways: 


[_] It prefixes the statement with the character >. 


[_] It shows the line in a bolder or brighter font. (You can use screen-custo- 
mization commands to change this highlighting method.) 


If you set a breakpoint in the disassembly, the debugger also highlights the 
associated C statement. If you set a breakpoint in the C source, the debugger 
also highlights the associated statement in the disassembly. (If more than one 
assembly language statement is associated with a C statement, the debugger 
highlights the first of the associated assembly language statements.) 


_FILE: sample.c 


000045> meminit () ; 
A breakpoint is set at 00. 6 for (i=0; i<0x50000; i++) 
this C statement; 000047 
notice how the line is 000048 call (i); 
highlighted. 


A breakpoint is also 
set at the associated 
assembly language 
statement (it’s 
highlighted, too). 


— DISASSEMBL 1 
000006 1540030 Sri SEES 
000007 62£00057* > CALL MEMINIT I 
000008 08640000 Tpr 0,84 | 


Note: 


[.] After execution is halted by a breakpoint, you can continue program 
execution by reissuing any of the run or single-step commands. 


[_.} Up to 200 breakpoints can be set. 
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Setting a Software Breakpoint 


There are several ways to set a software breakpoint: 


1) Point to the line of assembly language code or C code where you'd like to 
set a breakpoint. 


2) Click the left button. 


Repeating this action clears the breakpoint. 


1) Make the FILE or DISASSEMBLY window the active window. 


2) Use the arrow keys to move the cursor to the line of code where you'd like 
to set a breakpoint. 


3) Press the key. 


Repeating this action clears the breakpoint. 


If you know the address where you'd like to set a software breakpoint, you can 
use the BA (breakpoint add) command. This command is useful because it 
doesn’t require you to search through code to find the desired line. The syntax 
for the BA command is: 


ba address 


This command sets a breakpoint at address. This parameter can be an abso- 
lute address, any C expression, the name of a C function, or the name of an 
assembly language label. You cannot set multiple breakpoints at the same 
statement. 
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8.2 Clearing a Software Breakpoint 


| 
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br 


bd 


There are several ways to clear a breakpoint. If you clear a breakpoint from 
an assembly language statement, the breakpoint is also cleared from any 
associated C statement; if you clear a software breakpoint from aC statement, 
the software breakpoint is also cleared from the associated statement in the 
disassembly. 


1) Point to a breakpointed assembly language or C statement. 


2) Click the left button. 


1) Use the arrow keys or the DASM command to move the cursor to a break- 
pointed assembly language or C statement. 


2) Press the key. 


If you want to clear all the software breakpoints that are set, use the BR (break- 
point reset) command. This command is useful because it doesn’t require you 
to search through code to find the desired line. The syntax for the BR command 
is: 


br 


If you’d like to clear one specific software breakpoint and you know the address 
of this breakpoint, you can use the BD (breakpoint delete) command. The syn- 
tax for the BD command is: 


bd address 


This command clears the breakpoint at address. This parameter can be an ab- 
solute address, any C expression, the name of a C function, or the name of 
an assembly language label. If no breakpoint is set at address, the debugger 
ignores the command. 
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8.3 Finding the Software Breakpoints That Are Set 


Sometimes you may need to know where software breakpoints are set. For 
example, the BD command’s address parameter must correspond to the ad- 
dress of a breakpoint that is set. The BL (breakpoint list) command provides 
an easy way to get a complete listing of all the software breakpoints that are 
currently set in your program. The syntax for this command is: 


bl 


The BL command displays a table of software breakpoints in the COMMAND 
window display area. BL lists all the software breakpoints that are set, in the 
order in which you set them. Here’s an example of this type of list: 


Address Symbolic Information 

00400065 

00400007 in main, at line 45, "c:\c3xhll\sample.c” 
00400066 


The address is the memory address of the breakpoint. The symbolic informa- 
tion identifies the function, line number, and filename of the breakpointed C 
statement: 


[_] If the breakpoint was set in assembly language code, you'll see only an 
address unless the statement defines a symbol. 


[_] If the breakpoint was set in C code, you'll see the address together with 
symbolic information. 
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Customizing the Debugger Display 


The debugger display is completely configurable; you can create the interface 
that is best suited for your use. Besides being able to size and position individu- 
al windows, you can change the appearance of many of the display features, 
such as window borders, how the current statement is highlighted, etc. In addi- 
tion, if you’re using a color display, you can change the colors of any area on 
the screen. Once you’ve customized the display to your liking, you can save 
the custom configuration for use in future debugging sessions. 


Topic Page 
9.1 Changing the Colors of the Debugger Display 9-2 
Area names: common display areas 9-3 

Area names: window borders 9-4 

Area names: COMMAND window 9-4 

Area names: DISASSEMBLY and FILE windows 9-5 

Area names: data-display windows 9-6 

Area names: menu bar and pulldown menus Ce 

9.2 Changing the Border Styles of the Windows 9-8 
9.3. Saving and Using Custom Displays 9-9 
Changing the default display for monochrome monitors 9-9 
Saving a custom display 9-9 
Loading a custom display 9-10 
Invoking the debugger with a custom display 9-11 
Returning to the default display 9-11 

9.4 Changing the Prompt 9-11 
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Changing the Colors of the Debugger Display 


9.1 Changing the Colors of the Debugger Display 


You can use the debugger with a color or a monochrome display; the com- 
mands described in this section are most useful if you have a color display. If 
you are using a monochrome display, these commands change the shades on 
your display. For example, if you are using a black-and-white display, these 
commands change the shades of gray that are used. 


color Youcanuse the COLOR or SCOLOR command to change the colors of areas 
> scolor 


in the debugger display. The format for these commands is: 


color area name, attribute; |, attributes [, attribute [, attribute] | 
scolor area name, attribute; [, attribute [, attribute3 [, attribute] ] | 


These commands are similar. However, SCOLOR updates the screen im- 
mediately, and COLOR doesn’t update the screen (the new colors/attributes 
take effect as soon as the debugger executes another command that updates 
the screen). Typically, you might use the COLOR command several times, fol- 
lowed by an SCOLOR command to put all of the changes into effect at once. 


The area name parameter identifies the areas of the display that are affected. 
The attributes identify how the areas are affected. Table 9—1 lists the valid val- 
ues for the attribute parameters. 


Table 9-1. Colors and Other Attributes for the COLOR and SCOLOR Commands 


(a) Colors 
black blue green cyan 
red magenta yellow white 


(b) Other attributes 
bright blink 
The first two attribute parameters usually specify the foreground and back- 


ground colors for the area. If you do not supply a background color, the debug- 
ger uses black as the background. 


Table 9-2 lists valid values for the area name parameters. This is a long list; 
the subsections following the table further identify these areas. 
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Table 9-2. Summary of Area Names for the COLOR and SCOLOR Commands 


menu_bar menu_border menu_entry menu_cmd 
menu_hilite menu_hicmd win_border win_hiborder 
win_resize field_text field_hilite field_edit 
field_label field_error cmd_prompt cmd_input 
cmd_cursor cmd_echo asm_data asm_cdata 
asm_label asm_clabel background blanks 
error_msg file_line file_eof file_text 
file_brk file_pc file_pc_brk 


Note: Listing order is left to right, top to bottom. 


You don’t have to type an entire attribute or area name; you need to type only 
enough letters to uniquely identify either parameter. If you supply ambiguous 
attribute names, the debugger interprets the names in this order: black, blue, 
bright, blink. If you supply ambiguous area names, the debugger interprets 
them in the order that they’re listed in Table 9—2 (left to right, top to bottom). 


The remainder of this section identifies these areas. 


Area names: common display areas 


rf 4 
background 
qv 
Es 
r di 
blanks Sd 
PU 1 
Pc 00£f00076 SP 00000755 RO 00000003 
R1 00000005 R2 00000007 R3 00000000 
R4 00000000 R5 00000000 R6 00000000 
R7 00000000 ARO 00001802 ARI 00000000 
Area identification Parameter name 
Screen background (behind all windows) background 
Window background (inside windows) blanks 
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Area names: window borders 


: ; WATCH { -— : 
an inactive eee win_border 
window | 
2: X+X 4 v 
3 PC 0x00400064 
/—_———— win_resize 
rt ‘CO! 
eerie TMS320C3x Debugger Version 4.60 ; 7% 
Copyright (a) 1989, 1993 Texas oe win_hiborder 
TMS320C3x ( 
Loading sample.out 
Done 
>>fj 
Area identification Parameter name 
Window border for any window that isn’t active win_border 
The reversed “L” in the lower right corner of a resizable win_resize 
window 
Window border of the active window win_hiborder 


Area names: COMMAND window 


COMMAND 


cmd_echo pone 


file sample.c 


wa eee 


error_msg Name “eee” not found 
>>> go main ae = 

cmd_prompt cmd_input cmd_cursor 
Area identification Parameter name 
Echoed commands in display area cmd_echo 
Errors shown in display area error_msg 
Command-line prompt cmd_prompt 
Text that you enter on the command line cmd_input 
Command-line cursor cmd_cursor 
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Area names: DISASSEMBLY and FILE windows 


@ asm_cdata > 
,— DISASSEMBLY- 1 
400000 0£2b000 main: PUSH ars————_4—_ file pc 
400001 080b014 LDI SP,AR3 | 7 
400002 02740002 ADDI 2, SE: 
asm_clabel 400003 0£240000 PUSH R4 v 
asm_label——77%0004 og640000 = uot 0,R4 ih file_brk 
asm_data 
file_text 
file_line-———_____[- FE: tl.c 
00038 extern Cali, A 
00039 extern meminit (): 
00040 main () file_pc_brk 
00041 { 
file_eof [teot | 
Area identification Parameter name 
Object code in DISASSEMBLY window that is associated asm_cdata 
with current C statement 
Object code in DISASSEMBLY window asm_data 
Addresses in DISASSEMBLY window asm_label 
Addresses in DISASSEMBLY window that are associated asm_clabel 
with current C statement 
Line numbers in FILE window file_line 
End-of-file marker in FILE window file_eof 
Text in FILE or DISASSEMBLY window file_text 
Breakpointed text in FILE or DISASSEMBLY window file_brk 
Current PC in FILE or DISASSEMBLY window file_pc 
Breakpoint at current PC in FILE or DISASSEMBLY win- _file_pc_brk 
dow 
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Area names: data-display windows 
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field_label 


field_text 


field_hilite 


MEMORY 
009000 0000004b 


a 


00000041 00000000 
000004 00000043 00000044 00000045 00000046 
000008 00000047 00000048 00000049 0000004a 
00000c 00000000 00000000 00000000 
000010 00000000 00000000 00000000 
000014 o000f}ooo 00000000 00000000 
field_edit field_error 


Area identification 


Parameter name 


Label of a window field (includes register names in CPU field_label 
window, addresses in MEMORY window, index numbers 
and labels in WATCH window, member names in DISP 


window) 


Text of a window field (includes data values for all data- field_text 
display windows) and of most command output messages 


in command window 


Text of a highlighted field field_hilite 
Text of a field that has an error (such as an invalid field_error 
memory location) 

Text of a field being edited (includes data values for all field_edit 


data-display windows) 
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Area names: menu bar and pulldown menus 


( menu_bar 
r 
(ipad Break Memory Color Mode 
, mentu_hilite 
menu_hicmd 
menu_cmd menu_enitry 
e menu_border gd 
Area identification Parameter name 
Top line of display screen; background to main menu menu_bar 
choices 
Border of any pulldown menu menu_border 
Text of a menu entry menu_entry 
Invocation key for a menu or menu entry menu_cmd 
Text for current (selected) menu entry menu_hilite 
Invocation key for current (selected) menu entry menu_hicmd 
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9.2 Changing the Border Styles of the Windows 


In addition to changing the colors of areas in the display, the debugger allows 
you to modify the border styles of the windows. 


border Use the BORDER command to change window border styles. The format for 


this command is: 
border [active window style] [, [| inactive window style] [, resize style] | 


This command can change the border styles of the active window, the inactive 
windows, and any window that is being resized. The debugger supports nine 
border styles. Each parameter for the BORDER command must be one of the 
numbers that identifies these styles: 


Index Style 

Double-lined box 

Single-lined box 

Solid 1/2-tone top, double-lined sides and bottom 
Solid 1/4-tone top, double-lined sides and bottom 
Solid box, thin border 

Solid box, heavy sides, thin top and bottom 

Solid box, heavy borders 

Solid 1/2-tone box 

Solid 1/4-tone box 


ON Oa KrF WwW PS + CO 


Here are some examples of the BORDER command. Note that you can skip 
parameters, if desired. 


border 6,7,8 Change style of active, inactive, and resize windows 
border 1,,2 Change style of active and resize windows 
border ,3 Change style of inactive window 


Note that you can execute the BORDER command as the Border selection on 
the Color pulldown menu. The debugger displays a dialog box so that you can 
enter the parameter values; in the dialog box, active window style is called 
foreground, and inactive window style is called background. 


Saving and Using Custom Displays 


9.3. Saving and Using Custom Displays 


The debugger allows you to save and use as many custom configurations as 
you like. 


When you invoke the debugger, it looks for a screen configuration file called 
init.clr. The screen configuration file defines how various areas of the display 
will appear. If the debugger doesn’t find this file, it uses the default screen con- 
figuration. Initially, init.clr defines screen configurations that exactly match the 
default configuration. 


The debugger supports two commands for saving and restoring custom 
screen configurations into files. The filenames that you use for restoring con- 
figurations must correspond to the filenames that you used for saving configu- 
rations. Note that these are binary files, not text files, so you can’t edit the files 
with a text editor. 


Changing the default display for monochrome monitors 


The default display is most useful with color monitors. The debugger highlights 
changed values, messages, and other information with color; this may not be 
particularly helpful if you are using a monochrome monitor. 


The debugger package includes another screen configuration file named 
mono.clr, which defines a screen configuration that can be used with 
monochrome monitors. The best way to use this configuration is to rename the 
file: 


1) Rename the original init.clr file—you might want to call it color.clr. 


2) Next, rename the mono.clr file. Call it init.clr. Now, whenever you invoke 
the debugger, it will automatically come up with a customized screen 
configuration for monochrome monitors. 


If you aren’t happy with the way that this file defines the screen configuration, 
you can customize it. 


Saving a custom display 


ssave Once you've customized the debugger display to your liking, you can use the 


SSAVE command to save the current screen configuration to a file. The format 
for this command is: 


ssave [filename] 
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This saves the screen resolution, border styles, colors, window positions, win- 
dow sizes, and (on PCs) video mode (EGA, VGA, CGA, etc.) for all debugging 
modes. 


The filename parameter names the new screen configuration file. You can in- 
clude path information (including relative pathnames); if you don’t specify path 
information, the debugger places the file in the current directory. If you don’t 
supply a filename, the debugger saves the current configuration into a file 
named init.clr. 


Note that you can execute this command as the Save selection on the Color 
pulldown menu. 


Loading a custom display 


sconfig Youcan use the SCONFIG command to restore the display to a particular con- 


figuration. The format for this command is: 
sconfig [filename] 


This restores the screen resolution, colors, window positions, window sizes, 
border styles, and (on PCs) video mode (EGA, CGA, MDA, etc.) saved in file- 
name. Screen resolution and video mode are restored either by changing the 
mode (on video cards with switchable modes) or by resizing the debugger 
screen (on other hosts). 


If you don’t supply a filename, the debugger looks for init.clr. The debugger 
searches for the file in the current directory and then in directories named with 
the D_DIR environment variable. 


Note that you can execute this command as the Load selection on the Color 
pulldown menu. 


i 


Note: 


The file created by the SSAVE command in this version of the debugger 
saves positional, screen size, and video mode information that was not 
saved by SSAVE in previous versions of the debugger. The format of this new 
information is not compatible with the old format. If you attempt to load an 
earlier version's SCONFIG file, the debugger will issue an error message 
and stop the load. 


| 


Saving and Using Custom Displays / Changing the Prompt 


Invoking the debugger with a custom display 


If you set up the screen in a way that you like and always want to invoke the 
debugger with this screen configuration, you have two choices for accomplish- 
ing this: 


[| Save the configuration in init.clr. 


[.} Add a line to the batch file that the debugger executes at invocation time 
(init.cmd). This line should use the SCONFIG command to load the cus- 
tom configuration. 


Returning to the default display 


If you saved a custom configuration into init.clr but don’t want the debugger to 
come up in that configuration, then rename the file or delete it. If you are in the 
debugger, have changed the configuration, and would like to revert to the de- 
fault, just execute the SCONFIG command without a filename. 


9.4 Changing the Prompt 


prompt The debugger enables you to change the command-line prompt by using the 


PROMPT command. The format of this command is: 
prompt new prompt 


The new prompt can be any string of characters, excluding semicolons and 
commas. If you type a semicolon or acomma, it terminates the prompt string. 


Note that the SSAVE command doesn’t save the command-line prompt as part 
of acustom configuration. The SCONFIG command doesn’t change the com- 
mand-line prompt. If you change the prompt, it stays changed until you change 
it again, even if you use SCONFIG to load a different screen configuration. 


If you always want to use a different prompt, you can add a PROMPT 
statement to the init.cmd file that the debugger executes at invocation time. 


You can also execute this command as the Prompt selection on the Color pull- 
down menu. 
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Chapter 10 


Profiling Code Execution 


The profiling environment is a special debugger environment that lets you col- 
lect execution statistics for your code. This environment is available on all de- 
bugger platforms except for DOS. 


Note that the profiling environment is separate from the basic debugging envi- 
ronment; the only way to switch between the two environments is by exiting 
and then reinvoking the debugger. 
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An Overview of the Profiling Process 


10.1 An Overview of the Profiling Process 


Profiling consists of five simple steps: 


Enter the profiling environment. See Entering the Profiling Envi- 
ronment, page 10-3. 
| 


[Se22 | Vv 


Identify the areas of code where See Defining Areas for Profiling, 
you'd like to collect statistics. page 10-5. 


Em V 


Identify the profiling session See Defining a Stopping Point, 

stopping points. page 10-13. 

Begin profiling. See Running a Profiling Ses- 
sion, page 10-15. 

sep 3] Z 

View the profile data. See Viewing Profile Data, page 

10-17. 
Note: 


When you compile a program that will be profiled, you must use the —g and 
the —as options. The —g option includes symbolic debugging information; the 
—as option ensures that you will be able to include ranges as profile areas. 


Cd 


A profiling strategy 


The profiling environment provides a method for collecting execution statistics 
about specific areas in your code. This gives you immediate feedback on your 
application’s performance. Here’s a suggestion for a basic approach to opti- 
mizing the performance of your program. 


1) Mark all the functions in your program as profile areas. 
) Runa profiling session; find the busiest functions. 

3) Unmark all the functions. 
) 


Mark the individual lines in the busy functions and run another profiling 
session. 
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10.2 Entering the Profiling Environment 


Entering the Profiling Environment 


The profiling environment is available on all debugger platforms except DOS. 
To enter the profiling environment, invoke the debugger with the —-profile op- 
tion. At the system command line, enter the appropriate command: 


emulator: 
simulator: 
EVM: 


emu3x -profile 
sim3x -profile 
evm30 -profile 


Use any additional debugger options that you desire (—b, —p, etc.). 


Restrictions of the profiling environment 


Some restrictions apply to the profiling environment: 


L] 
L] 


You'll always be in mixed mode. 


COMMAND, DISASSEMBLY, FILE, and PROFILE are the only windows 
available; additional windows, such as the WATCH window, cannot be 


opened. 


Breakpoints cannot be set. (However, you can use a similar feature called 
stopping points when you mark sections of code for profiling.) 


The profiling environment supports only a subset of the debugger com- 
mands. Table 10-1 lists the debugger commands that can and can’t be 


used in the profiling environment. 


Table 10-1. Debugger Commands That Can/Can'’t Be Used in the Profiling Environment 


Can be used 


FUNC 
IF/ELSE/ENDIF 
LOAD 


LOOP/ENDLOOP 


MA 


SCONFIG 
SIZE 
SLOAD 
SYSTEM 
TAKE 
UNALIAS 
USE 
VERSION 
WIN 
ZOOM 


Can’t be used 


ADDR MIX 
ASM MS 

BA NEXT 
BD PATCH 
BL RETURN 
BORDER RUN 

BR RUNB 

Cc RUNF 
CALLS SCOLOR 
CNEXT SETF 
COLOR SOUND 
CSTEP SSAVE 
DISP STEP 
FILL WA 

GO WD 
HALT WHATIS 
MEM WR 


Be sure you don’t use any of the “can’t be used” commands in your initial- 


ization batch file. 
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Using pulldown menus in the profiling environment 
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The debugger displays a different menu bar in the profiling environment: 


“ 


Load mAp Mark Enable Disable Unmark View Stop-points Profile 


dj 


The Load menu corresponds to the Load menu in the basic debugger environ- 
ment. The mAp menu provides memory map commands available from the 
basic Memory menu. The other entries provide access to profiling commands 
and features. 


The profiling environment’s pulldown menus operate similarly to the basic de- 
bugger pulldown menus. However, several of the menus have additional sub- 
menus. A submenu is indicated by a > character following a menu item. For 
example, here’s one of the submenus for the Mark menu: 


Mark 

Asm level > Line areas > 
Range areas > Explicitly 
Function areas > in one Function 


Chapter 11, Summary of Commands and Special Keys, shows which debug- 
ger commands are associated with the menu items in the basic debugger pull- 
down menus. Because the profiling environment supports over 100 profile- 
specific commands, it’s not practical to show the commands associated with 
the menu choices. Here’s a tip to help you with the profiling commands: the 
highlighted menu letters form the name of the corresponding debugger com- 
mand. For example, if you prefer the function-key approach to using menus, 
the highlighted letters in Mark— C level—-Line areas—in one Function show 
that you could press GD @), ©), ©, ®. This also shows that the correspond- 
ing debugger command is MCLF. 


Defining Areas for Profiling 


10.3 Defining Areas for Profiling 


Marking an area 


Within the profiling environment, you can collect statistics on three types of 
areas: 


[_| Individual lines in C or disassembly 
[|_| Ranges in C or disassembly 
[_] Functions in C only 


To identify any of these areas for profiling, mark the line, range, or function. You 
can disable areas so that they won’t affect the profile data, and you can re-en- 
able areas that have been disabled. You can also unmark areas that you are 
no longer interested in. 


The mouse is the simplest way to mark, disable, enable, and unmark tasks. 
The pulldown menus also support these tasks and more complex tasks. 


The following subsections explain how to mark, disable, re-enable, and un- 
mark profile areas by using the mouse or the pulldown menus. The individual 
commands are summarized in Restrictions of the profiling environment on 
page 10-3. Restrictions on profiling areas are summarized on page 10-12. 


Marking an area qualifies it for profiling so that the debugger can collect timing 
statistics about the area. 


Remember, to display C code, use the FILE or FUNC command; to display dis- 
assembly, use the DASM command. 


Notes: 


[_.] Marking an area in C does notmark the associated code in disassembly. 


[.] Areas can be nested; for example, you can mark a line within a marked 
range. The debugger will report statistics for both the line and the func- 
tion. 


[_} Ranges cannot overlap, and they cannot span function boundaries. 
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S Marking a line. These instructions apply to both C and disassembly. 


a 1) Point to the line you want to mark. 


if 2) Click the left mouse button. 
The beginning of the line will be highlighted with a blinking >>. 


1 3) Click the left mouse button again. 
The beginning of the line will be highlighted with Le> (line enabled). 


Marking a range. These instructions apply to both C and disassembly. 
\ 1) Point to the first line of the range you want to mark. 


10 2) Click the left mouse button. 
The beginning of the line will be highlighted with a blinking >>. 


\ 3) Point to the last line of the range. 


I 4) Click the left mouse button again. 
The beginning of the line will be highlighted with Re> (range enabled), 
marking the beginning of the range. The last line will be highlighted with 
<<, marking the end of the range. 


Marking a function. These instructions apply to C only. 


By 1) Point to the statement that declares the function you want to mark. 


10 2) Click the left mouse button. 
The beginning of the line will be highlighted with Fe> (function enabled). 
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Defining Areas for Profiling 


Table 10-2 lists the menu selections for marking areas. The highlighted areas 
show the keys that you can use if you prefer to use the function-key method 
of selecting menu choices. 


Table 10-2.Menu Selections for Marking Areas 


Disabling an area 


C only: Disassembly only: 

To mark this area Mark-—C level Mark—Asm level 
Lines Line areas —Line areas 
LJ By line numbert Explicitly Explicitly 
(} All lines in a function in one Function in one Function 
Ranges —Range areas —Range areas 
[J By line numberst Explicitly Explicitly 
Functions —Function areas 
(} By function name Explicitly : 

; not applicable 
(] All functions in a module in one Module PP 
(] All functions everywhere Globally 


TC areas are identified by line number; disassembly areas are identified by address. 


Attimes, itis useful to identify areas that you don’t want to impact profile statis- 
tics. To do this, you should disable the appropriate area. Disabling effectively 
subtracts the timing information of the disabled area from all profile areas that 
include or call the disabled area. Areas must be marked before they can be 
disabled. 


For example, if you have marked a function that calls a standard C function 
such as malloc(), you may not want malloc() to affect the statistics for the call- 
ing function. You could mark the line that calls malloc(), and then disable the 
line. This way, the profile statistics for the function would not include the statis- 
tics for malloc(). 


acca | 
Note: 


If you disable an area after you've already collected statistics on it, that in- 


formation will be lost. 
eee ee eee aN ggg | 
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The simplest way to disable an area is to use the mouse, as described below. 


S Disabling a line area: 


Ss 1) Point to the marked line. 
Il 2) Click the left mouse button once. 
The beginning of the line will be highlighted with Ld> (line disabled). 
Disabling a range area: 
1) Point to the marked line. 
Il 2) Click the left mouse button once. 


The beginning of the line will be highlighted with Rd> (range disabled). 


Disabling a function area: 


a 1) Point to the marked statement that declares the function. 


Il 2) Click the left mouse button once. 
The beginning of the line will be highlighted with Fd> (function disabled). 
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of selecting menu choices. 


Table 10-—3.Menu Selections for Disabling Areas 


C only: Disassembly only: 
To disable this area Disable—C level Disable—Asm level 
Lines —Line areas —Line areas 
LJ By line numbert Explicitly Explicitly 


[] All lines in a function 
(J All lines in a module 
(] All lines everywhere 


Ranges 

[J Byline numberst 

_] All ranges in a function 
(] All ranges in a module 
_] All ranges everywhere 


Functions 

_] By function name 

[J All functions in a module 
_] All functions everywhere 


All areas 

(] All areas in a function 
(} All areas in a module 
(_]} All areas everywhere 


sin one Function 
sin one Module 
—Globally 


—Range areas 


Explicitly 

in one Function 
in one Module 
Globally 


—Function areas 


Explicitly 
in one Module 
Globally 


~All areas 


sin one Function 
sin one Module 
Globally 


sin one Function 
in one Module 
—Globally 


—Range areas 


Explicitly 

in one Function 
in one Module 
Globally 


not applicable 


~All areas 


sin one Function 
sin one Module 
Globally 


Defining Areas for Profiling 


Table 10-3 lists the menu selections for disabling areas. The highlighted areas 
show the keys that you can use if you prefer to use the function-key method 


C and disassembly: 
Disable—Both levels 
—Line areas 
not applicable 
in one Function 
—in one Module 
—Globally 


—Range areas 
not applicable 
in one Function 
in one Module 
Globally 


—Function areas 
not applicable 
—in one Module 
Globally 


—All areas 
in one Function 
in one Module 
Globally 


t C areas are identified by line number; disassembly areas are identified by address. 
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Re-enabling a disabled area 


Table 10—4.Menu Selections for Enabling Areas 


When an area has been disabled and you would like to profile it once again, 
you must enable the area. To use the mouse, just point to the line, the function, 
or the first line of a range, and click the left mouse button; the range will once 
again be highlighted in the same way as a marked area. 


In addition to using the mouse, you can enable an area by using one of the 
commands listed in Table 10—4. However, the easiset way to enter these com- 
mands is by accessing them from the Enable menu. 


C only: Disassembly only: C and disassembly: 
To enable this area Enable-C level Enable—Asm level Enable-Both levels 
Lines —Line areas —Line areas —Line areas 
LJ By line numbert Explicitly Explicitly not applicable 
(j All lines in a function in one Function in one Function in one Function 
_} All lines in a module in one Module in one Module in one Module 
(J All lines everywhere Globally Globally Globally 


sin one Module 


sin one Module 


Ranges —Range areas —Range areas —Range areas 
LJ By line numberst —Explicitly —Explicitly not applicable 
(] All ranges in a function in one Function in one Function in one Function 
_] All ranges in a module in one Module in one Module in one Module 
_] All ranges everywhere Globally Globally Globally 
Functions —Function areas —Function areas 

By function nam Explicitl F not applicable 
4 By fu cu ss i i py not applicable : RE 
_] All functions in a module in one Module in one Module 
_] All functions everywhere Globally —Globally 
All areas ~All areas ~All areas ~All areas 
_] All areas in a function in one Function in one Function in one Function 


—in one Module 
Globally 


(] All areas in a module 
[(_.] All areas everywhere —Globally —Globally 
t Careas are identified by line number; disassembly areas are identified by address. 
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Unmarking an area 


OK 


Ht 


OK 


Defining Areas for Profiling 


If you want to stop collecting information about a specific area, unmark it. You 
can use the mouse or key method. 


Unmarking a line area: 

1) Point to the marked line. 

2) Click the right mouse button once. 

The line will no longer be highlighted. 

Unmarking a range area: 

1) Point to the marked line. 

2) Click the right mouse button once. 

The line will no longer be highlighted. 

Unmarking a function area: 

1) Point to the marked statement that defines the function. 


2) Click the right mouse button once. 


The line will no longer be highlighted. 
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Defining Areas for Profiling 


Table 10—5 lists the selections on the Unmark menu. 


Table 10-—5.Menu Selections for Unmarking Areas 


To unmark this area 


Lines 


Lj 
L] 
Lj 
L} 


Lj 
L) 
Lj 


Lj 
Lj 
L} 


Tt C areas are identified by line number; disassembly areas are identified by address. 


By line numbert 

All lines in a function 
All lines in a module 
All lines everywhere 


Ranges 


By line numberst 

All ranges in a function 
All ranges in a module 
All ranges everywhere 


Functions 


By function name 
All functions in a module 
All functions everywhere 


All areas 


All areas in a function 
All areas in a module 
All areas everywhere 


C only: 

Unmark-C level 

—Line areas 
Explicitly 
—in one Function 
—in one Module 
Globally 


—Range areas 
—Explicitly 
in one Function 
in one Module 
Globally 


—Function areas 
Explicitly 
—in one Module 
Globally 


All areas 
—in one Function 
—in one Module 
Globally 


Restrictions on profiling areas 
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Disassembly only: 
Unmark->Asm level 
—Line areas 
Explicitly 
—in one Function 
—in one Module 
Globally 


—Range areas 
—Explicitly 
in one Function 
in one Module 
Globally 


not applicable 


All areas 
—in one Function 
—in one Module 
Globally 


The following restrictions apply to profiling areas: 


LI] 


LJ 


C and disassembly: 
Unmark->Both levels 
—Line areas 
not applicable 
—in one Function 
—in one Module 
Globally 


—Range areas 
not applicable 
in one Function 
in one Module 
Globally 


—Function areas 
not applicable 
—in one Module 
Globally 


~All areas 
—in one Function 
—in one Module 
Globally 


There must be a minimum of three instructions between a delayed branch 
and the beginning of an area. 


An area cannot begin or end on the RPTS instruction or on the instruction 


to be repeated. 


An area cannot begin or end on the last instruction of a repeat block. 


Defining a Stopping Point 


10.4 Defining a Stopping Point 


Hu 


a 


Before you run aprofiling session, you mustidentify the point where the debug- 
ger should stop collecting statistics. By default, C programs contain an exitla- 
bel, and this is defined as the default stopping point when you load your pro- 
gram. (You can delete exit as a stopping point, if you wish.) If your program 
does not contain an exit label, or if you prefer to stop at a different point, you 
can define another stopping point. You can set multiple stopping points; the 
debugger will stop at the first one it finds. 


Each stopping point is highlighted in the FILE or DISASSEMBLY window with 
a * character at the beginning of the line. Even though no statistics can be 
gathered for areas following a stopping point, the areas will be listed in the 
PROFILE window. 


You can use the mouse or commands to add or delete a stopping point; you 
can also use commands to list or reset all the stopping points. 


_———————— “(6 000 a ——__——<ouoow oe  —It 
Note: 


You cannot seta stopping point on a statement that has already been defined 


as a part of a profile area. 
Soo eshS— |, | 


To set a stopping point: 


1) Point to the statement that you want to add as a stopping point. 


2) Click the right mouse button. 


To remove a stopping point: 


1) Point to the statement marking the stopping point that you want to delete. 


2) Click the right mouse button. 
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Defining a Stopping Point 


The debugger supports several commands for adding, deleting, resetting, and 


listing stopping points (described below); all of these commands can also be 
entered from the Stop-points menu. 


sa To add a stopping point, use the SA (stop add) command. The syntax for this 
command is: 


sa address 


This adds address as a stopping point. The address parameter can be a label, 
a function name, or a memory address. 


sd To delete a stopping point, use the SD (stop delete) command. The syntax for 
this command is: 


sd address 


This deletes address as a stopping point. As for SA, the address can be a label, 
a function name, or a memory address. 


sr To delete all the stopping points at once, use the SR (stop reset) command. 
The syntax for this command is: 


sr 


This deletes all stopping points, including the default exit (if it exists). 


sl To see a list of all the stopping points that are currently set, use the SL (stop 
list) command. The syntax for this command is: 


sl 
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Running a Profiling Session 


10.5 Running a Profiling Session 


pq 


Once you have defined profile areas and a stopping point, you can run a profil- 
ing session. You can run two types of profiling sessions: 


[__]| A full profile collects a full set of statistics for the defined profile areas. 


(J A quick profile collects a subset of the available statistics (it doesn’t col- 
lect exclusive or exclusive max data, which are described in Section 10.6). 
This reduces overhead because the debugger doesn’t have to track enter- 
ing/exiting subroutines within an area. 


The debugger supports commands for running both types of sessions. In addi- 
tion, the debugger supports a command that helps you to resume a profiling 
session. All of these commands can also be entered from the Profile menu. 


To run a full profiling session, use the PF (profile full) command. The syntax 
for this command is: 


pf starting point[, update rate] 


To run a quick profiling session, use the PQ (profile quick) command. The syn- 
tax for this command is: 


pq_ starting point [, update rate] 


The debugger will collect statistics on the defined areas between the starting 
point and the stopping point. The starting point parameter can be a label, a 
function name, or a memory address. There is no default starting point. 


The update rate is an optional parameter that determines how often the statis- 
tics listed in the PROFILE window will be updated. The update rate parameter 
can have one of these values: 


0 An update rate of 0 means that the statistics listed in the PROFILE 
window are not updated until the profiling session is halted. A “spin- 
ning wheel” character will be shown at the beginning of the PROFILE 
window label line to indicate that a profiling session is in progress. 0 is 
the default value. 


>1 If a number greater than or equal to 1 is supplied, the statistics in the 
PROFILE window are updated during the profiling session. If a value 
of 1 is supplied, the data will be updated as often as possible. When 
larger numbers are supplied, the data is updated less often. 


<0 If a negative number is supplied, the statistics listed in the PROFILE 
window are not updated until the profiling session is halted. The “spin- 
ning wheel” character is not displayed. 
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pr 


No matter which update rate you choose, you can force the PROFILE window 
to be updated during a profiling session by pointing to the window header and 
clicking a mouse button. 


After you enter a PF or PQ command, your program restarts and runs to the 
defined starting point. Profiling begins when the starting point is reached and 
continues until a stopping point is reached or until you halt the profiling session 
by pressing Esc). 


Use the PR command to resume a profiling session that has halted. The syntax 
for this command is: 


pr [clear data [, update rate]] 


The optional clear data parameter tells the debugger whether or not it should 
clear out the previously collected data. The clear data parameter can have one 
of these values: 


0 The profiler will continue to collect data (adding it to the existing 
data for the profiled areas) and to use the previous internal profile 
stacks. 0 is the default value. 


nonzero All previously collected profile data and internal profile stacks are 
cleared. 


The update rate parameter is the same as for the PF and PQ commands. 


Viewing Profile Data 


10.6 Viewing Profile Data 


The statistics collected during a profiling session are displayed in the PRO- 
FILE window. Figure 10—1 shows an example of this window. 


Figure 10-1. An Example of the PROFILE Window 


profile data 
PROFILE = = A 
Area Name Count Inclusive Incl-Max Exclusive Excl-Max 
AR 00£00001-00£00008 L 65 65 19 19 
profile < CL <sample>#58 1 50 50 7 7 
areas CR <sample>#59-64 1 87 87 44 44 
CF call() 24 1623 99 1089 55) 
AL meminit 1 3 3 3 a \f 
AL 0O0£00059 disabled 


The example in Figure 10—1 shows the PROFILE window with some default 
conditions: 


[_] Column headings show the labels for the default set of profile data, includ- 
ing Count, Inclusive, Incl-Max, Exclusive, and Excl-Max. 


[_] The data is sorted on the address of the first line in each area. 


[] All marked areas are listed, including disabled areas. 


You can modify the PROFILE window to display selected profile areas or differ- 
ent data; you can also sort the data differently. The following subsections ex- 
plain how to do these things. 


Note: 


To reset the PROFILE display back to its default characteristics, use 
View—Reset. 


|) 


Viewing different profile data 


By default, the PROFILE window shows a set of statistics labeled as Count, 
Inclusive, Incl-Max, Exclusive, and Excl-Max. The address, which is not part 
of the default statistics, can also be displayed. Table 10-6 describes the statis- 
tic that each field represents. 
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Table 10-6. Types of Data Shown in the PROFILE Window 


Label 
Count 


Inclusive 


Incl-Max 
(inclusive maximum) 


Exclusive 


Excl-Max 
(exclusive maximum) 


Address 
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Profile data 
The number of times a profile area is entered during a session. 


The total execution time (cycle count) of a profile area, including the execution time 
of any subroutines called from within the profile area. 


The maximum inclusive time for one iteration of a profile area. 


If the profiled code contains no flow control (Such as conditional processing), inclu- 
sive-maximum will equal the inclusive timing divided by the count. 


The total execution time (cycle count) of a profile area, excluding the execution time 
of any subroutines called from within the profile area. 


In general, the exclusive data provides the best statistics for comparing the execution 
time of one profile area to another area. 


The maximum exclusive time for one iteration of a profile area. 


The memory address of the line. If the area is a function or range, the Address field 
shows the memory address of the first line in the area. 


In addition to viewing this data in the default manner, you can view each of 
these statistics individually. The benefit of viewing them individually is that in 
addition to a cycle count, you are also supplied with a percentage indication 
and a histogram. 


In order to view the fields individually, you can use the mouse—just point to the 
header line in the PROFILE window and click a mouse button. You can also 
use the View—>Data menu to select the field you’d like to display. When you 
use the left mouse button to click on the header, fields are displayed individual- 
ly in the order listed below on the left. (Use the right mouse button to go in the 
opposite direction.) On the right are the corresponding menu selections. 


count View—Data Count 

Incltisive Inclusive 

Ine ansts —+Inclusive Max 
ERG —Exclusive 
excliuen: —Exclusive Max 
Address —Address 

| 
Default >All 


One advantage of using the mouse is that you can change the display while 
you're profiling. 


Data accuracy 


Sorting profile data 


Viewing Profile Data 


During a profiling session, the debugger sets many internal breakpoints and 
issues a series of RUNB commands. As a result, the processor is momentarily 
halted when entering and exiting profiling areas. This stopping and starting 
can affect the cycle count information (due to pipeline flushing and the me- 
chanics of software breakpoints) so that it varies from session to session. This 
method of profiling is referred to as intrusive profiling. 


Treat the data as relative, not absolute. The percentages and histograms are 
relevant only to the cycle count from the starting point to the stopping point— 
not to overall performance. Even though the cycle counts may change if you 
profiled the same area twice, the relationship of that area to other profiled 
areas should not change. 


By default, the data displayed in the PROFILE window is sorted on the memory 
addresses of the displayed areas. The area with the least significant address 
is listed first, followed by the area with the most significant address, etc. When 
you view fields individually, the data is automatically sorted from highest cycle 
count to lowest (instead of by address). 


You can sort the data on any of the data fields by using the View—Sort menu. 
For example, to sort all the data based on the values of the Inclusive field, use 
View—Sort—Inclusive; the area with the highest Count field will display first, 
and the area with the lowest Count field will display last. This applies even 
when you are viewing individual fields. 


Viewing different profile areas 


By default, all marked areas are listed in the PROFILE window. You can modify 
the window to display selected areas. To do this, use the selections on the 
View—Filter pulldown menu; these selections are summarized in Table 10-7. 
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Table 10—7.Menu Selections for Displaying Areas in the PROFILE Window 


To view these areas 


Lines 

(] By line number 

(} All lines in a function 
(j All lines in a module 
_j All lines everywhere 


Ranges 

(J By line numbers 

(J All ranges in a function 
(] All ranges in a module 
_] All ranges everywhere 


Functions 

_} By function name 

[J All functions in a module 
_] All functions everywhere 


All areas 

_] All areas in a function 
(j All areas in a module 
(_] All areas everywhere 


C only: 
View->Filter>C level 
—Line areas 
Explicitly 
—in one Function 
—in one Module 
Globally 


—Range areas 
Explicitly 
in one Function 
in one Module 
Globally 


—Function areas 
Explicitly 
—in one Module 
Globally 


—Range areas 
—in one Function 
—in one Module 
Globally 


Interpreting session data 


Disassembly only: 
View-Filter>Asm level 
—Line areas 
Explicitly 
—in one Function 
—in one Module 
Globally 


—Range areas 
Explicitly 
in one Function 
in one Module 
Globally 


not applicable 


—Range areas 
—in one Function 
—in one Module 
Globally 


C and disassembly: 
View—Filter—Both levels 
—Line areas 
not applicable 
in one Function 
in one Module 
Globally 


—Range areas 
not applicable 
in one Function 
in one Module 
Globally 


—Function areas 
not applicable 
in one Module 
Globally 


—Range areas 
in one Function 
in one Module 
Globally 


General information about a profiling session is displayed in the COMMAND 
window during and after the session. This information identifies the starting 
and stopping points. It also lists statistics for three important areas: 


I 
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Run cycles shows the number of execution cycles consumed by the pro- 
gram from the starting point to the stopping point. 


Profile cycles equals the run cycles minus the cycles consumed by dis- 


abled areas. 


Hits shows the number of internal breakpoints encountered during the 


profiling session. 


Viewing Profile Data 


Viewing code associated with a profile area 


H 


You can view the code associated with a displayed profile area. The debugger 
will update the display so that the associated C or disassembly statements are 
shown in the FILE or DISASSEMBLY windows. 


Use the mouse to select the profile area in the PROFILE window and display 
the associated code: 


1) Point to the appropriate area name in the PROFILE window. 


2) Click the left mouse button. 


The area name and the associated C or disassembly statement will be high- 
lighted. To view the code associated with another area, point and click again. 


If you are attempting to show disassembly, you may have to make several at- 
tempts because program memory can be accessed only when the target is not 
running. 
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Saving Profile Data to a File 


10.7 Saving Profile Data to a File 


oe 
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vaa 


You may want to run several profiling sessions during a debugging session. 
Whenever you start a new profiling session,the results of the previous session 
are lost. However, you can save the results of the current profiling session to 
a system file. There are two commands that you can use to do this: 


To save the contents of the PROFILE window to a system file, use the VAC 
(view save current) command. The syntax for this command is: 


vac filename 


This saves only the current view; if, for example, you are viewing only the 
Count field, then only that information will be saved. 


To save all data for the currently displayed areas, use the VAA (view save all) 
command. The syntax for this command is: 


vaa_ filename 


This saves all views of the data—including the individual count, inclusive, 
etc.—with the percentage indications and histograms. 


Both commands write profile data to filename. The filename can include path 
information. There is no default filename. If filename already exists, the com- 
mand will overwrite the file with the new data. 


Note that if the PROFILE window displays only a subset of the areas that are 
marked for profiling, data is saved only for those areas that are displayed. (For 
VAC, the currently displayed data will be saved for the displayed areas. For 
VAA, all data will be saved for the displayed areas.) If some areas are hidden 
and you want to save all the data, be sure to select View—Reset before saving 
the data to a file. 


The file contents are in ASCII and are formatted in exactly the same manner 
as they are displayed (or would be displayed) in the PROFILE window. The 
general profiling-session information that is displayed in the COMMAND win- 
dow is also written to the file. 


Chapter 11 


Summary of Commands 
and Special Keys 


This chapter summarizes the debugger’s basic and profiling commands and 
special key sequences. 


Topic Page 
11.1 Functional Summary of Debugger Commands 11-2 
Changing modes 11-3 
Managing windows AES 
Displaying and changing data nies} 
Performing system tasks 11-4 
Displaying files and loading programs 11-5 
Managing breakpoints 11-5 
Customizing the screen 11-5 
Memory mapping 11-6 
Running programs 11-7 
Profiling commands 11-8 

11.2 How the Menu Selections Correspond to Commands 11-8 
Program-execution commands 11-9 
File/load commands 11-9 
Breakpoint commands 11-9 
Watch commands 11-9 
Memory commands 11-10 
Screen-configuration commands 11-10 
Mode commands 11-10 
Interrupt-simulation commands 11-10 

11.3 Alphabetical Summary of Debugger Commands 11-11 
11.4 Summary of Profiling Commands 11-48 
11.5 Summary of Special Keys 11-52 
Editing text on the command line 11-52 
Using the command history 11-52 
Switching modes 11-53 
Halting or escaping from an action 11-53 
Displaying pulldown menus 11-53 
Running code 11-54 
Selecting or closing a window 11-54 
Moving or sizing a window 11-54 
Scrolling through a window’s contents 11-55 
Editing data or selecting the active field 11-55 
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Functional Summary of Debugger Commands 


11.1 Functional Summary of Debugger Commands 


This section summarizes the debugger commands according to these catego- 
ries: 


Changing modes. These commands enable you to switch freely between 
the three debugging modes (auto, mixed, and assembly). You can also se- 
lect these commands from the Mode pulldown menu. 


Managing windows. These commands enable you to select the active 
window and move or resize the active window. You can also perform these 
functions with the mouse. 


Displaying and changing data. These commands enable you to display 
and evaluate a variety of data items. Some of these commands are also 
available on the Watch pulldown menu. 


Performing system tasks. These commands enable you to perform sev- 
eral DOS-like functions and provide you with some control over the target 
system. 


Displaying files and loading programs. These commands enable you 
to change the displays in the FILE and DISASSEMBLY windows and to 
load object files into memory. Several of these commands are available 
on the Load pulldown menu. 


Managing breakpoints. These commands provide you with acommand- 
line method for controlling software breakpoints and are also available 
through the Break pulldown menu. You can also set/clear breakpoints in- 
teractively. 


Customizing the screen. These commands allow you to customize the 
debugger display, then save and later reuse the customized displays. You 
can also use the Color pulldown menu to access these commands. 


Memory mapping. These commands enable you to define the areas of 
target memory that the debugger can access. You can also use the 
Memory pulldown menu to access these commands. 


Running programs. These commands provide you with a variety of 
methods for running your programs in the debugger environment. The 
basic run and single-step commands are available on the menu bar. 


Profiling commands. These commands enable you to collect execution 
statistics for your code. Commands can be entered from the pulldown 
menus or on the command line. 


Changing modes 


Managing windows 
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Displaying and changing data 


Use this 
To do this command See page 
Put the debugger in assembly mode asm 11-13 
Put the debugger in auto mode for debugging C code c 11-15 
Put the debugger in mixed mode mix 11-28 
Use this 
To do this command See page 
Reposition the active window move 11-29 
Resize the active window size 11-39 
Select the active window win 11-46 
Make the active window as large as possible zoom 11-47 
Use this 
To do this command See page 
Evaluate and display the result of a C expression ?sett 11-11 
Display the values in an array or structure or display disp 11-18 
the value that a pointer is pointing to 
Evaluate a C expression without displaying the results eval 11-21 
Display a different range of memory inthe MEMORY mem 11-27 
window 
Display an pop-up MEMORY window memi,mem2, 11-27 
mem3 
Change the default format for displaying data values setf 11-38 
Continuously display the value of a variable, register, wa 11-45 
or memory location within the WATCH window 
Delete a data item from the WATCH window wd 11-46 
Show the type of a data item whatis 11-46 
Delete all data items from the WATCH window and wr 11-47 
close the WATCH window 
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Functional Summary of Debugger Commands 


Performing system tasks 


Use this 


To do this 
Define your own command string 


Change the current working directory from within the 
debugger environment 


Clear all displayed information from the COMMAND 
window display area 


List the contents of the current directory or any other 
directory 


Record the information shown in the COMMAND 
window display area 


Display a string to the COMMAND window while 
executing a batch file 


Conditionally execute debugger commands in a 
batch file 


Loop debugger commands in a batch file 
Exit the debugger 


Reset the target system (emulator only), the simula- 
tor, or the EVM. 


Associate a beeping sound with the display of error 
messages 


Enter any operating-system command or exit to a 
system shell 


Execute commands from a batch file 
Delete an alias definition 


Name additional directories that can be searched 
when you load source files 


command 
alias 
cd/chdir 


cls 

dir 

dlog 

echo 
if/else/endif 
loop/endloop 
quit 

reset 

sound 


system 


take 
unalias 


use 


See page 
11-12 
11-15 


11-16 


11-18 


11-20 


11-21 


11-23 


11-24 
11-34 
11-34 


11-40 
11-42 


11-43 
11-43 
11-44 
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Displaying files and loading programs 


Use this 
To do this command See page 
Display C and/or assembly language code at aspecif- addr 11-12 
ic point 
Reopen the CALLS window calls 11-15 
Display assembly language code at a specific ad- dasm 11-18 
dress 
Display a text file in the FILE window file 11-22 
Display a specific C function func 11-22 
Load an object file load 11-24 
Modify disassembly with the patch assembler patch 11-31 
Load only the object-code portion of an object file reload 11-34 
Load only the symbol-table portion of an object file  sload 11-40 

Managing breakpoints 

Use this 
To do this command See page 
Add a software breakpoint ba 11-13 
Delete a software breakpoint bd 11-13 
Display a list of all the software breakpoints that are bl 11-13 
set 
Reset (delete) all software breakpoints br 11-14 


Customizing the screen 


Use this 
To do this command See page 
Change the border style of any window border 11-14 
Change the screen colors, but don’t update the color 11-16 
screen immediately 
Change the command-line prompt prompt 11-33 
Change the screen colors and update the screen im-  scolor 11-36 
mediately 
Load and use apreviously saved custom screen con-_ sconfig 11-37 
figuration 
Save a custom screen configuration ssave 11-41 
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Memory mapping 


Use this 


To do this command See page 
Initialize a block of memory fill 11-22 
Add an address range to the memory map ma 11-25 
Enable or disable memory mapping map 11-26 
Connect a simulated I/O port to an input or output file mc 11-26 
(simulator only) 

Delete an address range from the memory map md 11-27 
Disconnect a simulated I/O port (simulator only) mi 11-28 
Display a list of the current memory map settings ml 11-28 
Reset the memory map (delete all ranges) mr 11-30 
Save a block of memory to a system file ms 11-30 
Connect an input file to the pin pinc 11-32 
Disconnect the input file from the pin pind 11-32 


List the pins that are connected to the input files pinl 11-32 


Running programs 


Functional Summary of Debugger Commands 


To do this 


Single-step through assembly language or C code 
one C statement at a time; step over function calls 


Single-step through assembly language or C code, 
one C statement at a time 


Run a program up to a certain point 


Halt the target system after executing a RUNF com- 
mand (emulator and EVM only) 


Single-step through assembly language or C code; 
step over function calls 


Reset the target system (emulator only), simulator, or 
EVM 


Reset the program entry point 


Execute code in a function and return to the function’s 
caller 


Run a program 


Run a program with benchmarking (count the number 
of CPU clock cycles consumed by the executing por- 
tion of code) 


Disconnect the emulator from the target system and 
run free (emulator and EVM only) 


Single-step through assembly language or C code 
Execute commands from a batch file 
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Use this 
command 
cnext 


cstep 


go 
halt 


next 


reset 


restart 


return 


run 


runb 


runf 


step 
take 


See page 


11-16 


11-17 


11-23 
11-23 


11-30 


11-34 


11-34 
11-35 


11-35 


11-35 


11-36 


11-41 
11-43 
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Profiling commands 


All of the profiling commands can be entered from the pulldown menus. In 
many cases, using the pulldown menus is the easiest way to enter some of 
these commands. For this reason and also because there are over 100 profil- 
ing commands, most of these commands are not described individually in this 
chapter (as the basic debugger commands are). 


Listed below are some of the profiling commands that you might choose to en- 
ter from the command line instead of from a menu; these commands are also 
described in the alphabetical command summary. The remaining profiling 
commands are summarized in Section 11.4 on page 11-48. 


Use this 
To do this command See page 
Run a full profiling session pf 11-31 
Run a quick profiling session pq 11-33 
Resume a profiling session pr 11-33 
Add a stopping point sa 11-36 
Delete a stopping point sd 11-37 
List all the stopping points sl 11-39 
Delete all the stopping points sr 11-40 
Save all the profile data to a file vaa 11-44 
Save currently displayed profile data to a file vac 11-44 
Reset the display in the PROFILE window to show _ vr 11-45 


all areas and the default set of data 


11.2 How the Menu Selections Correspond to Commands 


The following sample screens illustrate the relationship of the basic debugger 
commands to the menu bar and pulldown menus. 


Remember, you can use the menus with or without a mouse. To access amenu 
from the keyboard, press the key and the letter that’s highlighted in the 
menu name. (For example, to display the Load menu, press @).) Then, 
to make a selection from the menu, press the letter that’s highlighted in the 
command you’ve selected. (For example, on the Load menu, to execute Fille, 
press ©).) If you don’t want to execute a command, press °’ to close the 
menu. 


How the Menu Selections Correspond to Commands 


——_—_———"r'wnwnnnsnnnannnnnnnnnaanaaiililii[iliraar[rlr['pwnanaanananaaaaaaaaaaaaa) 
Note: 


Because the profiling environment supports over 100 profile-specific com- 
mands, it’s not practical to show the commands associated with the profile 
menu choices. 


Program-execution commands 


RUN command 


Run=F5 (without a parameter) 


— STEP command 


Bure (without a parameter) 


— NEXT command 


Next=F10 (without a parameter) 


File/load commands 


fii RESET command 


FILE command 


File 


Breakpoint commands 


Break BA command 


Add 
Delete 
Reset 
List 


BD command 


BR command 


BL command 


Watch commands 


Watch WA command 


Add 
Delete 
Reset 


WD command 


Load LOAD command 
Zod RELOAD command 
Reload 

Symbols SLOAD command 
REstart RESTART command 


WR command 
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How the Menu Selections Correspond to Commands 


Memory commands 


Memo 


MA command 


Add 


Delete 
Reset 


Lise 


cy bier 
ies _=4 MD command 


_| EE MR Command 
ML command 


Enable 77]—_——_____—____ MAP command 


ypaeaLaL 
Save 


—_i FILL command 


Connect 


Err 


MS command 
MC command 


pisCont | 


MI command 


Screen-configuration commands 


SCONFIG command 


Color 
Load SSAVE command 
Save 
Config SCOLOR command 
Border BORDER command 
Prompt 

PROMPT command 


Mode commands 


C command 
ASM command 


MIX command 


. 


Interrupt-simulation commands 


Mode 


PINC command 


Li 


Connect 
Disconnect 


PIND command 


PINL command 
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Alphabetical Summary of Debugger Commands ? 


11.3 Alphabetical Summary of Debugger Commands 


Syntax 
Menu selection 


Environments 


Description 


There are two debugger environments: the basic debugger environment and 
the profiling environment. Some debugger commands can be used in both en- 
vironments; some can be used in only one of the environments. Each com- 
mand description identifies the applicable environments for the command. 


Commands are not case sensitive; to emphasize this, command names are 
shown in both uppercase and lowercase throughout this book. 


Evaluate Expression 


2 expression |, display format] 


none 


basic debugger L] profiling 


The ? (evaluate expression) command evaluates an expression and shows 
the result in the COMMAND window display area. The expression can be any 
C expression, including an expression with side effects. However, you cannot 
use a string constant or function call in the expression. If the result of expres- 
sion is not an array or structure, then the debugger displays the results in the 
COMMAND window. If expressionis a structure or array, ? displays the entire 
contents of the structure or array; you can halt long listings by pressing (Esc). 


When you use the optional display format parameter, data will be displayed in 
one of the following formats: 


Parameter Result Parameter Result 


* Default for the data type oO Octal 

c ASCII character (bytes) p Valid address 

d Decimal s ASCII string 

e Exponential floating point u Unsigned decimal 
f Decimal floating point x Hexadecimal 
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addr, alias Alphabetical Summary of Debugger Commands 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Display Code at Selected Address 
addr address 
addr function name 


none 


basic debugger L] profiling 


Use the ADDR command to display C code or the disassembly at a specific 
point. ADDR’s behavior changes, depending on the current debugging mode: 


[(_] In assembly mode, ADDR works like the DASM command, positioning the 
code starting at address or at function name as the first line of code in the 
DISASSEMBLY window. 


[_] In aC display, ADDR works like the FUNC command, displaying the code 
starting at address or at function name in the FILE window. 


[_] In mixed mode, ADDR affects both the DISASSEMBLY and FILE win- 
dows. 


Note: 


ADDR affects the FILE window only if the specified addressis in aC function. 
| 


Define Custom Command String 


alias [alias name |, command string” ] | 


none 


basic debugger profiling 


The ALIAS command allows you to associate one or more debugger com- 
mands with a single alias name. You can include as many debugger com- 
mands in the command string as you like, as long you separate them with 
semicolons and enclose the entire string of commands in quotation marks. You 
can also identify debugger-command parameters by a percent sign followed 
by a number (%1, %2, etc.). The total number of characters for an individual 
command (expanded to include parameter values) is limited to 132. 


Previously defined alias names can be included as part of the definition for a 
new alias. 


To find the current definition of an alias, enter the ALIAS command with the 
alias name only. To see a list of all defined aliases, enter the ALIAS command 
with no parameters. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 


Alphabetical Summary of Debugger Commands asm, ba, bd, bl 


Enter Assembly Mode 


asm 


MoDe—-Asm 


basic debugger LJ profiling 


The ASM command changes from the current debugging mode to assembly 
mode. If you’re already in assembly mode, the ASM command has no effect. 


Add Software Breakpoint 


ba address 
Break—>Add 


basic debugger LJ profiling 


The BA command sets a software breakpoint at a specific address. This com- 
mand is useful because it doesn’t require you to search through code to find 
the desired line. The address can be an absolute address, any C expression, 
the name of a C function, or the name of an assembly language label. 


Delete Software Breakpoint 


bd address 
Break— Delete 
basic debugger L] profiling 


The BD command clears a software breakpoint at a specific address. The ad- 
dresscan be an absolute address, any C expression, the name of aC function, 
or the name of an assembly language label. 


List Software Breakpoint 


bl 
Break—List 
basic debugger L] profiling 


The BL command provides an easy way to get a complete listing of all the soft- 
ware breakpoints that are currently set in your program. It displays a table of 
breakpoints in the COMMAND window display area. BL lists all the break- 
points that are set, in the order in which you set them. 
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border, br Alphabetical Summary of Debugger Commands 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Change Style of Window Border 


border [active windowstyle][, [ inactive window style] [,resize window style] | 


Color—>Border 


basic debugger LJ profiling 


The BORDER command changes the border style of the active window, the 
inactive windows, and the border style of any window that you’re resizing. The 
debugger supports nine border styles. Each parameter for the BORDER com- 
mand must be one of the numbers that identifies these styles: 


Index Style 

Double-lined box 

Single-lined box 

Solid 1/2-tone top, double-lined sides/bottom 
Solid 1/4-tone top, double-lined sides/bottom 
Solid box, thin border 

Solid box, heavy sides, thin top/bottom 

Solid box, heavy borders 

Solid 1/2-tone box 

Solid 1/4-tone box 


ON Oa FW YP + CO 


Note that you can execute the BORDER command as the Border selection on 
the Color pulldown menu. The debugger displays a dialog box so that you can 
enter the parameter values; in the dialog box, active window style is called 
foreground, and inactive window style is called background. 


Reset Software Breakpoints 


br 


Break—>Reset 


basic debugger LJ profiling 


The BR command clears all software breakpoints that are set. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Alphabetical Summary of Debugger Commands C, Calls, cd, chdir 


Enter Auto Mode 


c 


MoDe-C (auto) 
basic debugger L] profiling 


The C command changes from the current debugging mode to auto mode. If 
you're already in auto mode, then the C command has no effect. 


Open CALLS Window 


calls 


none 


basic debugger LJ profiling 


The CALLS command displays the CALLS window. The debugger displays 
this window automatically when you are in auto/C or mixed mode. However, 
you can close the CALLS window; the CALLS command opens the window 
again. 


Change Directory 


cd_ [directory name] 
chdir [directory name] 


none 


basic debugger profiling 


The CD or CHDIR command changes the current working directory from within 
the debugger. You can use relative pathnames as part of the directory name. 
If you don’tuse a pathname, the CD command displays the name of the current 
directory. Note that this command can affect any other command whose pa- 
rameter is a filename, such as the FILE, LOAD, and TAKE commands, when 
it is used with the USE command. You can also use the CD command to 
change the current drive. For example, 

cdc: 


ed d:\csource 
ed c:\c3xh1l1 
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cls, cnext, color 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Alphabetical Summary of Debugger Commands 


Clear Screen 


cls 


none 


basic debugger profiling 


The CLS command clears all displayed information from the COMMAND win- 
dow display area. 


Single-Step C, Next Statement 


cnext 
Next=F10 (in C code) 


basic debugger LJ profiling 


The CNEXT command is similar to the CSTEP command. It runs a program 
one C statement at a time, updating the display after executing each state- 
ment. If you’re using CNEXT to step through assembly language code, the de- 
bugger won’t update the display until it has executed all assembly language 
statements associated with a single C statement. Unlike CSTEP, CNEXT 
steps over function calls rather than stepping into them—you don’t see the 
single-step execution of the function call. 


[expression] 


The expression parameter specifies the number statements that you want to 
single-step. You can also use a conditional expression for conditional single- 
step execution (the Running code conditionally discussion, page 6-17, dis- 
cusses this in detail). 


Change Screen Colors 


color area name, attribute, [,attributes [,attribute3 [,attribute,] | ] 


none 


basic debugger L] profiling 


The COLOR command changes the color of specified areas of the debugger 
display. COLOR doesn’t update the display; the changes take effect when 
another command, such as SCOLOR, updates the display. The area name pa- 
rameter identifies the area of the display that is affected. The attributes identify 
how the area is affected. The first two attribute parameters usually specify the 
foreground and background colors for the area. If you do not supply a back- 
ground color, the debugger uses black as the background. 


Syntax 
Menu selection 


Environments 


Description 


Alphabetical Summary of Debugger Commands color, cstep 


Valid values for the attribute parameters include: 


black blue green cyan 
red magenta yellow white 
bright blink 


Valid values for the area name parameters include: 


menu_bar menu_border menu_entry menu_cmd 
menu_hilite menu_hicmd win_border win_hiborder 
win_resize field_text field_hilite field_edit 
field_label field_error cmd_prompt cmd_input 
cmd_cursor cmd_echo asm_data asm_cdata 
asm_label asm_clabel background blanks 
error_msg file_line file_eof file_text 
file_brk file_pc file_pc_brk 


You don’t have to type an entire attribute or area name; you need to type only 
enough letters to uniquely identify the attribute. If you supply ambiguous aftrib- 
utenames, the debugger interprets the names in this order: black, blue, bright, 
blink. If you supply ambiguous area names, the debugger interprets them in 
the order that they’re listed above (left to right, top to bottom). 


Single-Step C 


cstep [expression] 


Step=F8 (in C code) 
basic debugger LJ profiling 


The CSTEP single-steps through a program one C statement at a time, updat- 
ing the display after executing each statement. If you’re using CSTEP to step 
through assembly language code, the debugger won't update the display until 
it has executed all assembly language statements associated with a single C 
statement. 


If you’re single-stepping through C code and encounter a function call, the 
STEP command shows you the single-step execution of the called function 
(assuming that the function was compiled with the compiler’s —g debug op- 
tion). When function execution completes, single-step execution returns to the 
caller. If the function wasn’t compiled with the debug option, the debugger 
executes the function but doesn’t show single-step execution of the function. 
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cstep, dasm, dir, disp Alphabetical Summary of Debugger Commands 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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The expression parameter specifies the number statements that you want to 
single-step. You can also use a conditional expression for conditional single- 
step execution (the Running code conditionally discussion, page 6-17, dis- 
cusses this in detail). 


Display Disassembly at Specified Address 
dasm_ address 
dasm_ function name 


none 


basic debugger profiling 


The DASM command displays code beginning at a specific point within the 
DISASSEMBLY window. 


List Directory Contents 


dir [directory name] 


none 


basic debugger profiling 


The DIR command displays a directory listing in the display area of the 
COMMAND window. If you use the optional directory name parameter, the 
debugger displays a list of the specified directory’s contents. If you don’t use 
the parameter, the debugger lists the contents of the current directory. 


Open DISP Window 


disp expression [, display format| 


none 


basic debugger LJ profiling 


The DISP command opens a DISP window to display the contents of an array, 
structure, or pointer expression to a scalar type (of the form *pointer). If the 
expression is not one of these types, then DISP acts like a ? command. 


Alphabetical Summary of Debugger Commands disp 


Once you open a DISP window, you may find that a displayed member is itself 
an array, structure, or pointer: 


A member that is an array looks like this: [eal 
A member that is a structure looks like this: {...} 
A member that is a pointer looks like an address: 0x00000000 


You can display the additional data (the data pointed to or the members of the 
array or structure) in another DISP window by using the DISP command again, 
using the arrow keys to select the field and then pressing , or pointing the 
mouse cursor to the field and pressing the left mouse button. You can have up 
to 120 DISP windows open at the same time. 


When you use the optional display format parameter, data will be displayed in 
one of the following formats: 


Parameter Result Parameter Result 


i Default for the data type oO Octal 

c ASCII character (bytes) p Valid address 

d Decimal s ASCII string 

e Exponential floating point u Unsigned decimal 
f Decimal floating point xX Hexadecimal 


The display format parameter can be used only when you are displaying a sca- 
lar type, an array of scalar type, or an individual member of an aggregate type. 


You can also use the DISP command with a typecast expression to display 
memory contents in any format. Here are some examples: 

disp *0 

disp *(float *)123 

disp *(char *)0x111 


This shows memory in the DISP window as an array of locations; the location 
that you specify with the expression parameter is member [0], and all other 
locations are offset from that location. 
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dlog Alphabetical Summary of Debugger Commands 


Cy §ecord COMMAND Window Display 


Syntax 


Menu selection 


Environments 


Description 
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dlog filename [,{a | w}] 


or 


dlog close 


none 
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The DLOG command allows you to record the information displayed in the 
command window into a log file. 


(_] To begin recording the information shown in the COMMAND window dis- 


play area, use: 
dlog filename 


Log files can be executed by using the TAKE command. When you use 
DLOG to record the information from the COMMAND window display area 
into a log file called filename, the debugger automatically precedes all er- 
ror or progress messages and command results with a semicolon to turn 
them into comments. This way, you can easily re-execute the commands 
in your log file by using the TAKE command. 


To end the recording session, enter: 


dlog close 


If necessary, you can write over existing log files or append additional informa- 
tion to existing files. The optional parameters of the DLOG command control 
how existing log files are used: 


LJ 


J 


Appending to an existing file. Use the a parameter to open an existing 
file to which to append the information in the display area. 


Writing over an existing file. Use the w parameter to open an existing 
file to write over the current contents of the file. Note that this is the default 
action if you specify an existing filename without using either the a or w 
options; you will lose the contents of an existing file if you don’t use the ap- 
pend (a) option. 


Alphabetical Summary of Debugger Commands echo, else, endif, endloop, eval 


Syntax 


Menu selection 


Environments 


Description 


Description 


Description 


Description 


Menu selection 


Environments 


Description 


Echo String to COMMAND Window 


echo string 


none 


basic debugger profiling 


The ECHO command displays string in the COMMAND window display area. 
This command works only in a batch file, and you can’t use quote marks 
around the string. Note that any leading blanks in your command string are re- 
moved when the ECHO command is executed. 


Execute Alternative Debugger Commands 


ELSE provides an alternative list of debugger commands in the IF/ELSE/EN- 
DIF command sequence. See page 11-23 for more information about the IF/ 
ELSE/ENDIF commands. 


Terminate Conditional Sequence 


ENDIF identifies the end of the IF/ELSE/ENDIF command sequence. See 
page 11-23 for more information about the IF/ELSE/ENDIF commands. 


Terminate Looping Sequence 


ENDLOOP identifies the end of the LOOP/ENDLOOP command sequence. 
See page 11-24 for more information about the LOOP/ENDLOOP commands. 


Evaluate Expression 
eval expression 
e expression 


none 
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The EVAL command evaluates an expression like the ? command does but 
does not show the resultin the COMMAND window display area. EVAL is use- 
ful for assigning values to registers or memory locations in a batch file (where 
it’s not necessary to display the result). 
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file, fill, func Alphabetical Summary of Debugger Commands 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Display Text File 


file filename 


Load—File 
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The FILE command displays the contents of any text file in the FILE window. 
The debugger continues to display this file until you run a program and halt in 
aC function. This commandis primarily intended for displaying C source code. 
You can view only one text file at a time. 


You are restricted to displaying files that are 65,518 bytes long or less. 


Fill Memory 


fill address, length, data 


Memory-—>Fill 
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The FILL command fills a block of memory with a specified value. This com- 
mand has three parameters: 


|_| The address parameter identifies the beginning of the block. 


[|_| The length parameter defines the number of 32-bit words that will be filled. 


[|_| The data parameter is the value that is placed in each word in the block. 


Display Function 
fune function name 
func address 


none 
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The FUNC command displays a specified C function in the FILE window. You 
can identify the function by its name or its address. Note that FUNC works the 
same way FILE works, but with FUNC you don’t need to identify the name of 
the file that contains the function. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


if/else/endif 


Syntax 


Menu selection 


Environments 


Description 
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Run to Specified Address 


go_ [address] 


none 
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The GO command executes code up to a specific point in your program. If you 
don’t supply an address parameter, then GO acts like a RUN command with- 
out an expression parameter. 


Halt Target System EVM & Emulator Only 


halt 


none 
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The HALT command halts the target system after you’ve entered a RUNF 
command. When you invoke the debugger, it automatically executes a HALT 
command. Thus, if you enter a RUNF, quit the debugger, and later reinvoke 
the debugger, you will effectively reconnect the emulator to the target system 
and run the debugger in its normal mode of operation. 


Conditionally Execute Debugger Commands 


if expression 
debugger commands 
[else 

debugger commands] 
endif 


none 
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These commands allow you to execute debugger commands conditionally in 
a batch file. If the expression is nonzero, the debugger executes the com- 
mands between the IF and the ELSE or ENDIF. Note that the ELSE portion of 
the command is optional. 
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if/else/endif, load, loop/endloop Alphabetical Summary of Debugger Commands 


Syntax 


Menu selection 


Environments 


Description 


CoXo) of{=Valo | Core) o) 


Syntax 


Menu selection 


Environments 


Description 
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You can substitute a keyword for the expression. Keywords evaluate to true 
(1) or false (0). You can use the following keywords with the IF command: 


_] $$EMU$$ (tests for the emulator version of the debugger) 
_] $$SIM$$ (tests for the simulator version of the debugger) 
_] $$EVM$$ (tests for the EVM version of the debugger) 


The conditional commands work with the following provisions: 


[_| You can use conditional commands only in a batch file. 


[_] You must enter each debugger command on a separate line in the batch 
file. 


[_} You can’t nest conditional commands within the same batch file. 


Load Executable Object File 


load object filename 


Load— Load 
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The LOAD command loads both an object file and its associated symbol table 
into memory. In effect, the LOAD command performs both a RELOAD and an 
SLOAD. If you don’t supply an extension, the debugger looks for filename.out. 
Note that the LOAD command clears the old symbol table and closes the 
WATCH and DISP windows. 


Loop Through Debugger Commands 


loop expression 
debugger commands 
endloop 


none 
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The LOOP/ENDLOOP commands allow you to set up a looping situation in a 
batch file. These looping commands evaluate in the same method as in the run 
conditional command expression: 


[_] If you use an expression that is not Boolean, the debugger evaluates the 
expression as a loop count. 


[__] If you use a Boolean expression, the debugger executes the command re- 
peatedly as long as the expression is true. 


Syntax 
Menu selection 


Environments 


Description 
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The LOOP/ENDLOOP commands work under the following conditions: 
[| You can use LOOP/ENDLOOP commands only in a batch file. 


[.} You must enter each debugger command on a separate line in the batch 
file. 


[_.] You can’t nest LOOP/ENDLOOP commands within the same batch file. 


Add Block to Memory Map 


ma address, length, type 


Memory—Add 
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The MA command identifies valid ranges of target memory. A new memory 
map must not overlap an existing entry. If you define a range that overlaps an 
existing range, the debugger ignores the new range. 


[_] The address parameter defines the starting address of a range. This pa- 
rameter can be an absolute address, any C expression, the name of a C 
function, or an assembly language label. 


[|_|] The /ength parameter defines the length of the range. This parameter can 
be any C expression. 


[|_|] The type parameter identifies the read/write characteristics of the memory 
range. The type must be one of these keywords: 


Use this keyword as the type 


To identify this kind of memory parameter 

read-only memory R, ROM, or READONLY 
write-only memory W, WOM, or WRITEONLY 
read/write memory WR or RAM 

no-access memory PROTECT 

input port IPORT 

output port OPORT 

input/output port IOPORT 
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map, mc_ Alphabetical Summary of Debugger Commands 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Enable Memory Mapping 


map {on | off} 


Memory—Enable 
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The MAP command enables or disables memory mapping. In some instances, 
you may want to explicitly enable or disable memory. Note that disabling 
memory mapping can cause bus fault problems in the target because the de- 
bugger may attempt to access nonexistent memory. 


Connect a Simulated I/O Port to a File Simulator Only 


mc_ port address, page, filename, {READ | WRITE} 


Memory—Connect 
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The MC command connects IPORT, OPORT, or IOPORT to an input or output 
file. Before you can connect the port, you must add it to the memory map with 
the MA command. 


(_} The port address parameter defines the address of the I/O port. This pa- 
rameter can be an absolute address, any C expression, the name of a C 
function, or an assembly language label. 


[__] The filename parameter can be any filename. If you connect a port to read 
from a file, the file must exist, or the MC command will fail. 


[|_| The final parameter is specified as READ or WRITE and defines how the 
file will be used (for input or output, respectively). 


The file is accessed during an LDI or STI instruction to the associated port ad- 
dress. Amaximum of one input and one output file can be connected to asingle 
port; multiple ports can be connected to a single file. 


This port-connect feature can also be used for simulation of serial ports. The 
data transmit and data receive registers of serial port O and serial port 1 can 
be connected to files. 


Syntax 
Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Description 
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Delete Block From Memory Map 


md_ address 


Memory—Delete 
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The MD command deletes a range of memory from the debugger’s memory 
map. The address parameter identifies the starting address of the range of 
memory. Note that if you are attempting to delete a simulated I/O port, you 
must first disconnect it. 


Modify MEMORY Window Display 


mem[#]_ expression |, display format| 
none 


The MEM command identifies a new starting address for the block of memory 
displayed in a MEMORY window. The optional extension number (#) opens an 
additional MEMORY window, allowing you to view a separate block of 
memory. The debugger displays the contents of memory at expression in the 
first data position in the MEMORY window. The end of the range is defined by 
the size of the window. The expressioncan be an absolute address, a symbolic 
address, or any C expression. 


When you use the optional display format parameter, memory will be dis- 
played in one of the following formats: 


Parameter Result Parameter Result 


. Default for the data type fo) Octal 

c ASCII character (bytes) p Valid address 

d Decimal u Unsigned decimal 
e Exponential floating point X Hexadecimal 

f Decimal floating point 
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mi, mix, ml 


Syntax 
Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Alphabetical Summary of Debugger Commands 


Disconnecting |/O Port Simulator Only 


mi port address, {READ | WRITE} 


Memory—>DisConn 
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The MI command disconnects a simulated I/O port from its associated system 
file. 


The port address parameter identifies the address of the I/O port, which must 
have been previously defined with the MC command. 


Enter Mixed Mode 
mix 
MoDe->Mixed 
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The MIX command changes from the current debugging mode to mixed mode. 
If you're already in mixed mode, the MIX command has no effect. 


List Memory Map 


ml 


Memory->List 
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The ML command lists the memory ranges that are defined for the debugger’s 
memory map. The ML command lists the starting address, ending address, 
and read/write characteristics of each defined memory range. 


move 


Syntax 
Menu selection 
Environments 


Description 
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Move Active Window 


move [X position, Y position [, width, length ] | 


none 
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The MOVE command moves the active window to the specified XY position. 
If you choose, you can resize the window while you move it (see the SIZE com- 
mand for valid width and length values). You can use the MOVE command in 
one of two ways: 


__} By supplying a specific X position and Y position or 


[_] By omitting the X position and Y position parameters and using function 
keys to interactively move the window. 


You can move a window by defining a new XY position for the window’s upper 
left corner. Valid X and Y positions depend on the screen size and the window 
size. X positions are valid if the X position plus the window width in characters 
is less than or equal to the screen width in characters. Y positions are valid if 
the Y position plus the widow height is less than or equal to the screen height 
in lines. 


For example, if the window is 10 characters wide and 5 lines high and the 
screen size is 80 x 25, the command move 70, 20 would put the lower right- 
hand corner of the window in the lower right-hand corner of the screen. No X 
value greater than 70 or Y value greater than 20 would be valid in this example. 


If you enter the MOVE command without X positionand Y positionparameters, 
you can use arrow keys to move the window. 


QO Moves the active window down one line. 

® Moves the active window up one line. 

Moves the active window left one character position. 
Moves the active window right one character position. 


When you're finished using the arrow keys, you must press or (2). 
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mr, ms, next Alphabetical Summary of Debugger Commands 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Reset Memory Map 


mr 


Memory—Reset 
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The MR command resets the debugger’s memory map by deleting all defined 
memory ranges from the map. 


Save Memory Block to File 


ms_ address, length, filename 


Memory—Save 
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The MS command saves the values in a block of memory to a system file; files 
are saved in COFF format. 


|_| The address parameter identifies the beginning of the block. 


[|_| The /ength parameter defines the length, in words, of the block. This pa- 
rameter can be any C expression. 


[__] The filename is asystem file. If you don’t supply an extension, the debug- 
ger adds an .obj extension. 


Single-Step, Next Statement 


next [expression] 


Next=F10 (in disassembly) 
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The NEXT command is similar to the STEP command. If you're in C code, the 
debugger executes one C statement at a time. In assembly or mixed mode, 
the debugger executes one assembly language statement at a time. Unlike 
STEP, NEXT never updates the display when executing called functions; 
NEXT always steps to the next consecutive statement. Unlike STEP, NEXT 
steps over function calls rather than stepping into them—you don't see the 
single-step execution of the function call. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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The expression parameter specifies the number of statements that you want 
to single-step. You can also use a conditional expression for conditional single- 
step execution (the Running code conditionally discussion, page 6-17, dis- 
cusses this in detail). 


Patch Assemble 


patch address, assembly language instruction 


none 
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The PATCH command allows you to patch-assemble disassembly state- 
ments. The address parameter identifies the address of the statement you 
want to change. The assembly language instruction parameter is the new 
statement you want to use at address. 


Profile, Full 


pf starting point|, update rate] 


Profile—>Full 
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The PF command initiates a RUN and collects a full set of statistics on the de- 
fined areas between the starting point and the first-encountered stopping 
point. The starting point parameter can be a label, a function name, or a 
memory address. 


The optional update rate parameter determines how often the PROFILE win- 
dow willbe updated. The update rate parameter can have one of these values: 


Value Description 


0 This is the default. Statistics are not updated until the session is halted 
(although you can force an update by clicking the mouse in the window 
header). A “spinning wheel” character is shown to indicate that a profiling 
session is in progress. 


21 Statistics are updated during the session. A value of 1 means that data 
is updated as often as possible. 


<0 Statistics are not updated until the profiling session is halted, and the 
“spinning wheel” character is not displayed. 
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pinc, pind, pinl 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Alphabetical Summary of Debugger Commands 


Connect Pin Simulator Only 


pinc pinname, filename 


Pin—Connect 
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The PINC command connects an input file to interrupt pin. 


_] The pinname parameter identifies the interrupt pin and must be one of the 
four interrupt pins (INTO-INT3). 


_] The filename parameter is the name of your input file. 


Disconnect Pin Simulator Only 


pind pinname 


Pin—Disconnect 
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The PIND command disconnects an input file from an interrupt pin. The 
pinname parameter identifies the interrupt pin and must be one of the four 
interrupt pins, (INTO-INT3). 


List the Interrupt Pins Simulator Only 


pinl 
Pin-List 
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The PINL command displays all of the pins—unconnected pins first, followed 
by the connected pins. For a connected pin, the simulator displays the name 
of the pin and the absolute pathname of the file in the COMMAND window. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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Profile, Quick 


pq_ starting point [, update rate] 


Profile—>Quick 
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The PQ command initiates a RUN command and collects a subset of the avail- 
able statistics on the defined areas between the starting point and the first-en- 
countered stopping point. PQ is similar to PF, except that PQ doesn’t collect 
exclusive or exclusive max data. 


The update rate parameter is the same as for the PF command. 


Resume Profile Session 


pr [clear data [, update rate] | 


Profile>Resume 
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The PR command resumes the last profiling session (initiated by PF or PQ), 
starting from the current program counter. 


The optional clear data parameter tells the debugger whether or not it should 
clear out the previously collected data. The clear dataparameter can have one 
of these values: 


Value Description 

0 This is the default. The profiler will continue to collect data, adding it to 
the existing data for the profiled areas, and to use the previous internal 
profile stacks. 

nonzero’ All previously collected profile data and internal profile stacks are 


cleared. 


The update rate parameter is the same as for the PF and PQ commands. 


Change Command-Line Prompt 


prompt new prompt 


Color—Prompt 
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The PROMPT command changes the command-line prompt. The new prompt 
can be any string of characters (note that a semicolon or comma ends the 
string). 
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quit, reload, reset, restart Alphabetical Summary of Debugger Commands 


Syntax 


Menu selection 


Environments 


Description 


reload 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Exit Debugger 

quit 

none 

basic debugger profiling 


The QUIT command exits the debugger and returns to the operating system. 


Reload Object Code 


reload [object filename] 


Load—Reload 
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The RELOAD command loads only an object file without loading its 
associated symbol table. This is useful for reloading a program when target 
memory has been corrupted. If you enter the RELOAD command without 
specifying a filename, the debugger reloads the file that you loaded last. 


Reset Target System 


reset 


Load—ReseT 
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The RESET command resets the target system (emulator only), simulator, or 
EVM and reloads the monitor. Note that this is a software reset. 


Reset PC to Program Entry Point 
restart 
rest 


Load—REstart 
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The RESTART or REST command resets the program to its entry point. (This 
assumes that you have already used one of the load commands to load a pro- 
gram into memory.) 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Return to Function’s Caller 
return 
ret 


none 


basic debugger L] profiling 


The RETURN or RET command executes the code in the current C function 
and halts when execution reaches the caller. Breakpoints do not affect this 
command, but you can halt execution by pressing the left mouse button or 
pressing (ESC). 


Run Code 


run 
Run=F5 


basic debugger LJ profiling 


The RUN command is the basic command for running an entire program. The 
command's behavior depends on the type of parameter you supply: 


[expression] 


__] Ifyou don’t supply an expression, the program executes until it encounters 
a breakpoint or until you press the left mouse button or press (S80). 


[_] If you supply a logical or relational expression, this becomes a conditional 
run (described in detail on page 6-17). 


|_| If you supply any other type of expression, the debugger treats the expres- 
sion as a count parameter. The debugger executes count instructions, 
halts, and updates the display. 


Benchmark Code 


runb 


none 
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The RUNB command executes a specific section of code and counts the num- 
ber of CPU clock cycles consumed by the execution. In order to operate cor- 
rectly, execution must be halted by a software breakpoint. After RUNB execu- 
tion halts, the debugger stores the number of cycles into the CLK pseudoregis- 
ter. Fora complete explanation of the RUNB command and the benchmarking 
process, read Section 6.7, Benchmarking, on page 6-19. 
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runf, sa, scolor 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Alphabetical Summary of Debugger Commands 


Run Free EVM & Emulator Only 


runf 


none 


basic debugger LJ profiling 


The RUNF command disconnects the emulator or EVM from the target system 
while code is executing. When you enter RUNF, the debugger clears all break- 
points, disconnects the emulator or EVM from the target system, and causes 
the processor to begin execution at the current PC. You can quit the debugger, 
or you can continue to enter commands. However, any command that causes 
the debugger to access the target at this time produces an error. 


The HALT command stops a RUNF; note that the debugger automatically 
executes a HALT when the debugger is invoked. 


Add Stopping Point 


sa address 
Stop-points—Add 
profiling 


The SA command adds a stopping point at address. The address can be a la- 
bel, a function name, or a memory address. 
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Change Screen Colors 


scolor area name, attribute, [, attributes [, attribute3 [, attribute] | | 


Color—Config 
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The SCOLOR command changes the color of specified areas of the debugger 
display and updates the display immediately. The area name parameter identi- 
fies the area of the display that is affected. The attributes identify how the area 
is affected. The first two attribute parameters usually specify the foreground 
and background colors for the area. If you do not supply a background color, 
the debugger uses black as the background. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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Valid values for the attribute parameters include: 


black blue green cyan 
red magenta yellow white 
bright blink 


Valid values for the area name parameters include: 


menu_bar menu_border menu_entry menu_cmd 
menu_hilite menu_hicmd win_border win_hiborder 
win_resize field_text field_hilite field_edit 
field_label field_error cmd_prompt cmd_input 
cmd_cursor cmd_echo asm_data asm_cdata 
asm_label asm_clabel background blanks 
error_msg file_line file_eof file_text 
file_brk file_pc file_pc_brk 


You don’t have to type an entire attribute or area name; you need to type only 
enough letters to uniquely identify the attribute. If you supply ambiguous aftrib- 
utenames, the debugger interprets the names in this order: black, blue, bright, 
blink. If you supply ambiguous area names, the debugger interprets them in 
the order that they’re listed above (left to right, top to bottom). 


Load Screen Configuration 


sconfig [filename] 


Color—Load 


basic debugger profiling 


The SCONFIG command restores the display to a specified configuration. 
This restores the screen colors, window positions, window sizes, and border 
styles that were saved with the SSAVE command into filename. If you don’t 
supply a filename, the debugger looks for the init.clr file. The debugger 
searches for the specified file in the current directory and then in directories 
named with the D_DIR environment variable. 


Delete Stopping Point 


sd address 


Stop-points—Delete 
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The SD command deletes the stopping point at address. 
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setf Alphabetical Summary of Debugger Commands 


EU Set Default Data-Display Format 


Syntax 


Menu selection 


Environments 


Description 
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setf [data type, display format | 


none 
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The SETF command changes the display format for a specific data type. If you 
enter SETF with no parameters, the debugger lists the current display format 
for each data type. 


[_] The data type parameter can be any of the following C data types: 


char short uint ulong double 
uchar int long float ptr 


_] The display format parameter can be any of the following characters: 


Parameter Result Parameter Result 


. Default for the data type fo) Octal 

c ASCII character (bytes) p Valid address 

d Decimal s ASCII string 

e Exponential floating point u Unsigned decimal 
f Decimal floating point x Hexadecimal 


Only a subset of the display formats can be used for each data type. Listed 
below are the valid combinations of data types and display formats. 


Data Valid Display Formats Data Valid Display Formats 
Type c do x e f p s u|Type cdoxefpsu 
char (c) Vv vv V | long (d) Vv vv V 
uchar (d) V Vv Vv Vv V]ulong(d) Vv Vv Vv v V 
short(d) Vv Vv Vv V | float (e) Vv V 

int (d) Vvv Vv V | double (e) Vv V 

uint (d) VvvV Vv V | ptr (p) Vv Vv 


To return all data types to their default display format, enter: 


setf * 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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Size Active Window 


size [width, length | 


none 


basic debugger profiling 


The SIZE command changes the size of the active window. You can use the 
SIZE command in one of two ways: 


(| By supplying a specific width and length or 
[__] By omitting the width and /ength parameters and using function keys to in- 
teractively resize the window. 


Valid values for the width and length depend on the screen size and the win- 
dow position on the screen. If the window is in the upper left corner of the 
screen, the maximum size of the window is the same as the screen size minus 
one line. (The extra line is needed for the menu bar.) For example, if the screen 
size is 80 characters by 25 lines, the largest window size is 80 characters by 
24 lines. 


If a window is in the middle of the display, you can’t size it to the maximum 
height and width—you can size it only to the right and bottom screen borders. 
The easiest way to make a window as large as possible is to zoom it, as de- 
scribed on page 3-23. 


If you enter the SIZE command without width and length parameters, you can 
use arrow keys to size the window. 


Makes the active window one line longer. 

Makes the active window one line shorter. 

Makes the active window one character narrower. 
Makes the active window one character wider. 


YUOBE 


When you’re finished using the arrow keys, you must press or (#]. 


List Stopping Point 


sl 


Stop-points—List 
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The SL command lists all of the currently set stopping points. 
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sload, sound, sr 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Load Symbol Table 


sload object filename 


Load—Symbols 
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The SLOAD command loads the symbol table of the specified object file. 
SLOAD is useful in a debugging environment in which the debugger cannot, 
or need not, load the object code (for example, if the code is in ROM). SLOAD 
clears the existing symbol table before loading the new one but does not 
modify memory or set the program entry point. Note that SLOAD closes the 
WATCH and DISP windows. 


Enable Error Beep 


sound {on | off} 


none 


basic debugger 


You can cause a beep to sound every time a debugger error message is dis- 
played. This is useful if the COMMAND window is hidden (because you 
wouldn't see the error message). By default, sound is off. 


LJ profiling 


Reset Stopping Point 


sr 


Stop-points—Reset 


profiling 


The SR command resets (deletes) a// currently set stopping points. 


L] basic debugger 


ssave 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 
Environments 


Description 
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Save Screen Configuration 


ssave [filename] 


Color—>Save 
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The SSAVE command saves the current screen configuration to a file. This 
saves the screen colors, window positions, window sizes, and border styles. 
The filename parameter names the new screen configuration file. You can in- 
clude path information (including relative pathnames); if you don’t supply path 
information, the debugger places the file in the current directory. If you don’t 
supply a filename, then the debugger saves the current configuration into a file 
named init.clr and places the file in the current directory. 


Single-Step 


step [expression] 


Step=F8 (in disassembly) 


basic debugger CL] profiling 


The STEP command single-steps through assembly language or C code. If 
you're in C code, the debugger executes one C statement at a time. In assem- 
bly or mixed mode, the debugger executes one assembly language statement 
at a time. 


If you’re single-stepping through C code and encounter a function call, the 
STEP command shows you the single-step execution of the called function 
(assuming that the function was compiled with the compiler’s —g debug op- 
tion). When function execution completes, single-step execution returns to the 
caller. If the function wasn’t compiled with the debug option, the debugger 
executes the function but doesn’t show single-step execution of the function. 


The expression parameter specifies the number of statements that you want 
to single-step. You can also use a conditional expression for conditional single- 
step execution (the Running code conditionally discussion, page 6-17, dis- 
cusses this in detail). 
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system Alphabetical Summary of Debugger Commands 


Syntax 


Menu selection 


Environments 


Description 
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Enter DOS Command 


system [DOS command , flag] | 


none 
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The SYSTEM command allows you to enter DOS commands without explicitly 
exiting the debugger environment. 


If you enter SYSTEM with no parameters, the debugger will open a system 
shell and display the operating-system prompt. At this point, you can enter any 
DOS command. (In MS-DOS, available memory may limit the commands that 
you can enter.) When you finish, enter: 


exit 


If you prefer, you can supply the DOS command as a parameter to the 
SYSTEM command. If the result of the command is a message or other 
display, the debugger will blank the top of the debugger display to show the 
information. In this case, you can use the flag parameter to tell the debugger 
whether or not it should hesitate after displaying the information. Flag may be 
aQoral. 


0 If you supply a value of 0 for flag, the debugger immediately returns to 
the debugger environment after the last item of information is dis- 
played. 

1 If you supply a value of 1 for flag, the debugger does not return to the 


debugger environment until you press @). (This is the default.) 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Execute Batch File 


take batch filename [, suppress echo flag] 


none 
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The TAKE command tells the debugger to read and execute commands from 
a batch file. The batch filename parameter identifies the file that contains com- 
mands. 


By default, the debugger echoes the commands to the output area of the 
COMMAND window and updates the display as it reads the commands from 
the batch file. 


[__] Ifyou don’tuse the suppress echo flag parameter, or if you use it but supply 
a nonzero value, then the debugger behaves in the default manner. 


[__] If you would like to suppress the echoing and updating, use the value 0 for 
the suppress echo flag parameter. 


Delete Alias Definition 
unalias alias name 
unalias ~* 


none 


basic debugger profiling 
The UNALIAS command deletes defined aliases. 


_} Todelete a single alias, enter the UNALIAS command with an alias name. 
For example, to delete an alias named NEWMAP, enter: 


unalias NEWMAP 


(_] To delete all aliases, enter an asterisk instead of an alias name: 
unalias * 


Note that the * symbol does not work as a wildcard. 
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use, vaa, vac, version Alphabetical Summary of Debugger Commands 


Syntax 


Menu selection 


Environments 


Description 


WEE! 


Syntax 


Menu selection 


Environments 


Description 


vac 


Syntax 


Menu selection 


Environments 


Description 


version 


Syntax 


Menu selection 


Environments 


Description 
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Use New Directory 


use [directory name] 


none 
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The USE command allows you to name an additional directory that the debug- 
ger can search when looking for source files. You can specify only one directo- 
ry ata time. 


If you enter the USE command without specifying a directory name, the debug- 
ger lists all of the current directories. 


Save All Profile Data to a File 


vaa_ filename 


View—>Save—All views 
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The VAA command saves all statistics collected during the current profiling 
session. The data is stored in a system file. 


Save Currently Displayed Profile Data to a File 


vac filename 


View—Save—->Current view 
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The VAC command saves all statistics currently displayed in the PROFILE 
window. (Statistics that aren’t displayed aren’t saved.) The data is stored ina 
system file. 


Display the Current Debugger Version 


version 


none 


basic debugger profiler 


The VERSION command displays the debugger’s copyright date and the cur- 
rent version number of the debugger, silicon, etc. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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Reset PROFILE Window Display 


vr 
View—Reset 
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The VR command resets the display in the PROFILE window so that all 
marked areas are listed and statistics are displayed with default labels and in 
the default sort order. 


Add Item to WATCH Window 


wa_ expression [,| label], display format| 


Watch—Add 
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The WA command displays the value of expression in the WATCH window. If 
the WATCH window isn’t open, executing WA opens the WATCH window. The 
expression parameter can be any C expression, including an expression that 
has side effects. It's most useful to watch an expression whose value changes 
over time; constant expressions serve no useful function in the watch window. 
The /abe/l parameter is optional. When used, it provides a label for the watched 
entry. If you don’t use a /abel, the debugger displays the expression in the label 
field. 


When you use the optional display format parameter, data will be displayed in 
one of the following formats: 


Parameter Result Parameter Result 


7 Default for the data type oO Octal 

c ASCII character (bytes) p Valid address 

d Decimal s ASCII string 

e Exponential floating point u Unsigned decimal 
f Decimal floating point x Hexadecimal 


If you want to use a display format parameter without a /abe/ parameter, just 
insert an extra comma. For example: 


wa PC,,d 
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wd, whatis, win Alphabetical Summary of Debugger Commands 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 


Syntax 


Menu selection 


Environments 


Description 
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Delete Item From WATCH Window 


wd index number 


Watch—Delete 


basic debugger LJ profiling 


The WD command deletes a specific item from the WATCH window. The WD 
command's index number parameter must correspond to one of the watch in- 
dexes listed in the WATCH window. 


Find Data Type 


whatis symbol 


none 
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The WHATIS command shows the data type of symbolin the COMMAND win- 
dow display area. The symbol! can be any variable (local, global, or static), a 
function name, structure tag, typedef name, or enumeration constant. 


Select Active Window 


win WINDOW NAME 


none 
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The WIN command allows you to select the active window by name. Note that 
the WINDOW NAME is in uppercase (matching the name exactly as dis- 
played). You can spell out the entire window name, but you really need to spec- 
ify only enough letters to identify the window. 


If several of the same types of window are visible on the screen, don’t use the 
WIN command to select one of them. If you supply an ambiguous name (such 
as C, which could stand for CPU or CALLS), the debugger selects the first win- 
dow it finds whose name matches the name you supplied. If the debugger 
doesn't find the window you asked for (because you closed the window or mis- 
spelled the name), then the WIN command has no effect. 


Syntax 


Menu selection 


Environments 


Description 


Syntax 
Menu selection 


Environments 


Description 
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Reset WATCH Window 


wr 
Watch—Reset 
basic debugger LJ profiling 


The WR command deletes all items from the WATCH window and closes the 
window. 


Zoom Active Window 


zoom 


none 


basic debugger profiling 


The ZOOM command makes the active window as large as possible. To “un- 
zoom” a window, enter the ZOOM command a second time; this returns the 
window to its prezoom size and position. 


Summary of Commands and Special Keys 11-47 


Summary of Profiling Commands 


11.4 Summary of Profiling Commands 


The following tables summarize the profiling commands that are used for 
marking, enabling, disabling, and unmarking areas and for changing the dis- 
play in the PROFILE window. These commands are easiest to use from the 
pulldown menus, so they are not included in the alphabetical command sum- 
mary. The syntaxes for these commands are provided here so that you can 
include them in batch files. 


Table 11-1. Marking Areas 


To mark this area 
Lines 


(} All lines in a function 
Ranges 

(J By line numbers 
Functions 


_] By function name 


_} By line number, address 


[] All functions in a module 


_] All functions everywhere 


C only 


MCLE 
MCLF 


MCRE 


MCFE 


MCFM 
MCFG 


filename, line number 


function 


filename, line number, line number 


function 


filename 


Table 11-2. Disabling Marked Areas 


Disassembly only 


MALE address 
MALF function 


MARE. address, address 


not applicable 


To disable this area 

Lines 

[_} By line number, address 
(} All lines in a function 

_} All lines in a module 

(] All lines everywhere 
Ranges 

By line number, address 
All ranges in a function 


All ranges in a module 


Wooo 


All ranges everywhere 
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C only 


DCLE 
DCLF 
DCLM 
DCLG 


DCRE 
DCRF 
DCRM 
DCRG 


filename, line number 
function 


filename 


filename, line number 
function 


filename 


Disassembly only 


DALE 
DALF 
DALM 
DALG 


DARE 
DARF 
DARM 
DARG 


address 
function 


filename 


address 
function 


filename 


C and disassembly 


not applicable 
DBLF function 
DBLM filename 
DBLG 


not applicable 
DBRF function 
DBRM_ filename 
DBRG 
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Table 11-2. Disabling Marked Areas (Continued) 


To disable this area C only Disassembly only C and disassembly 
Functions 

(_} By function name DCFE function not applicable not applicable 

(J Allfunctionsina module DCFM filename DBFM filename 
_j All functions everywhere DCFG DBFG 

All areas 

(] All areas in a function DCAF function DAAF function DBAF function 

(] All areas in a module DCAM filename DAAM filename DBAM filename 
(] All areas everywhere DCAG DAAG DBAG 


Table 11-3. Enabling Disabled Areas 


To enable this area C only Disassembly only C and disassembly 
Lines 

(} By line number, address ECLE filename, line number EALE address not applicable 

[J All lines in a function ECLF function EALF function EBLF function 
_} All lines in a module ECLM filename EALM filename EBLM filename 
(} All lines everywhere ECLG EALG EBLG 

Ranges 

(] By line number, address ECRE filename, line number EARE address not applicable 

[J All ranges in a function ECRF function EARF function EBRF function 
(] All ranges in a module ECRM filename EARM filename EBRM filename 
_] All ranges everywhere ECRG EARG EBRG 
Functions 

(_} By function name ECFE function not applicable not applicable 

[J Allfunctions ina module ECFM filename EBFM filename 
[J Allfunctions everywhere ECFG EBFG 

All areas 

(] All areas in a function ECAF function EAAF function EBAF function 
(] All areas in a module ECAM filename EAAM filename EBAM filename 
(] All areas everywhere ECAG EAAG EBAG 
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Table 11-4. Unmarking Areas 


C only 


Disassembly only 


C and disassembly 


To unmark this area 


Lines 

_] By line number, address 
[} All lines in a function 

_} All lines in a module 

(} All lines everywhere 
Ranges 

[_] By line number, address 
(J All ranges in a function 
(] All ranges in a module 
_] All ranges everywhere 
Functions 

_} By function name 

(J All functions in a module 
_] All functions everywhere 
All areas 

[] All areas in a function 


(] All areas in a module 


_] All areas everywhere 


UCLE 
UCLF 
UCLM 
UCLG 


UCRE 
UCRF 
UCRM 
UCRG 


UCFE 
UCFM 
UCFG 


UCAF 
UCAM 
UCAG 


filename, line number 
function 


filename 


filename, line number 
function 


filename 


function 


filename 


function 


filename 


Table 11-5. Changing the PROFILE Window Display 


(a) Viewing specific areas 


UALE 
UALF 
UALM 
UALG 


address 
function 


filename 


UARE 
UARF 
UARM 
UARG 


address 
function 


filename 


not applicable 


UAAF function 
UAAM filename 
UAAG 


not applicable 
UBLF function 
UBLM filename 
UBLG 


not applicable 
UBRF function 
UBRM filename 
UBRG 


not applicable 
UBFM filename 
UBFG 


UBAF function 
UBAM filename 
UBAG 


To view this area 


C only 


Disassembly only C and disassembly 


Lines 

_] By line number, address 
(} All lines in a function 

_} All lines in a module 

_} All lines everywhere 
Ranges 

By line number, address 
All ranges in a function 


All ranges in a module 


VFCLE 
VFCLF 
VFCLM 
VFCLG 


VFCRE 
VFCRF 
VFCRM 
VFCRG 


filename, line number 
function 


filename 


filename, line number 
function 


filename 


VFALE 
VFALF 
VFALM 
VFALG 


address 
function 


filename 


VFARE 
VFARF 
VFARM 
VFARG 


address 
function 


filename 


not applicable 
VFBLF function 
VFBLM filename 
VFBLG 


not applicable 
VFBRF function 
VFBRM filename 
VFBRG 


All ranges everywhere 
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Table 11-5. Changing the PROFILE Window Display (Continued) 


To view this area 
Functions 

(] By function name 

[] All functions in a module 
(] All functions everywhere 
All areas 

(] All areas in a function 


(] All areas in a module 


(] All areas everywhere 


(b) Viewing different data 


C only 


VFCFE function 
VFCFM filename 
VFCFG 


VFCAF function 
VFCAM filename 
VFCAG 


To view this information 
Count 

Inclusive 

Inclusive, maximum 
Exclusive 

Exclusive, maximum 
Address 

All 


Use this 
command 


vbc 
VDI 

VDN 
VDE 
VDX 
VDA 
VDL 


Disassembly only C and disassembly 


not applicable not applicable 
VFBFM filename 
VFBFG 


VFAAF function VFBAF function 


VFAAM filename VFBAM_ filename 
VFAAG VFBAG 


(c) Sorting the data 


Use this 

To sort on this data command 
Count vsc 
Inclusive VSI 
Inclusive, maximum VSN 
Exclusive VSE 
Exclusive, maximum VSX 
Address VSA 

Data VSD 
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11.5 Summary of Special Keys 


The debugger provides function key, cursor key, and command key se- 
quences for performing a variety of actions: 


Editing text on the command line 
Using the command history 

Switching modes 

Halting or escaping from an action 
Displaying the pulldown menus 
Running code 

Selecting or closing a window 

Moving or sizing a window 

Scrolling through a window’s contents 
Editing data or selecting the active field 


DUUUUOUUOUOU 


Editing text on the command line 


Use these 
To do this function keys 


Enter the current command (note that if you press the return key 
in the middle of text, the debugger truncates the input text at the 
point where you press this key) 


Move back over text without erasing characters (CONTROL ) 
or 
BACK SPACE 


Move forward through text without erasing characters (CONTROL ) 
Move back over text while erasing characters DELETE ) 


Move forward through text while erasing characters (SPACE) 


Insert text into the characters that are already on the command INSERT _) 
line 


Using the command history 
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Use these 
To do this function keys 
Repeat the last command that you entered 


Move backward, one command at a time, through the command 
history 


Move forward, one command at a time, through the command 
history 
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Switching modes 


Use this 
To do this function key 
Switch debugging modes in this order: 


ce —_———+» assembly ——_+ aan 


Halting or escaping from an action 


The escape key acts as an end or undo key in several situations. 


Use this 
To do this function key 
(J Halt program execution ESC 
[_.]} Close a pulldown menu 
[} Undo an edit of the active field in a data-display window 

(pressing this key leaves the field unchanged) 
(] Halt the display of a long list of data in the display area of 
the COMMAND window 
Displaying pulldown menus 

Use these 
To do this function keys 
Display the Load menu (ALT) ) 
Display the Break menu (ALT) (B) 
Display the Watch menu CT) W 
Display the Memory menu (ALT) (MD) 
Display the Color menu (ALT) (C) 
Display the MoDe menu (ALT) (D) 
Display the Pin menu (ALT) (P} 
Display an adjacent menu © or 
Execute any of the choices from a displayed pulldown menu Press the high- 


lighted letter 
corresponding 
to your choice 
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Running code 


Use these 
To do this function keys 


Run code from the current PC (equivalent to the RUN command 
without an expression parameter) 


Single-step code from the current PC (equivalent to the STEP 
command without an expression parameter) 


Single-step code from the current PC; step over function calls F10 
(equivalent to the NEXT command without an expression 
parameter) 


Selecting or closing a window 


Use these 
To do this function keys 


Select the active window (pressing this key makes each window 
active in turn; stop pressing the key when the desired window 
becomes active) 


Close the CALLS, WATCH, DISP, or additional MEMORY window 
(the window must be active before you can close it) 


Moving or sizing a window 


You can use the arrow keys to interactively move a window after entering the 
MOVE or SIZE command without parameters. 


Use these 
To do this function keys 
(} Move the window down one line @ 
[_} Make the window one line longer 
[J Move the window up one line @ 
[J Make the window one line shorter 
[(_} Move the window left one character position © 
(} Make the window one character narrower 
J} Move the window right one character position Oo) 
[} Make the window one character wider 
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Scrolling a window’s contents 


These descriptions and instructions for scrolling apply to the active window. 
Some of these descriptions refer to specific windows; if no specific window is 
named, then the description/instructions refer to any window that is active. 


Use these 

To do this function keys 
Scroll up through the window contents, one window length at (PAGE UP ) 
atime 
Scroll down through the window contents, one window length (PAGE DOWN ) 
at a time 
Move the field cursor up, one line at a time Gi) 
Move the field cursor down, one line at a time WY) 
[J FILE window only: Scroll left 8 characters at a time ©) 
[| Other windows: Move the field cursor left 1 field; at the first 

field on a line, wrap back to the last fully displayed field on 

the previous line 
[J FILE window only: Scroll right 8 characters at a time 
[J Other windows: Move the field cursor right 1 field; at the last 


field on a line, wrap around to the first field on the next line 
FILE window only: Adjust the window's contents so that the first | (HOME) 
line of the text file is at the top of the window 
FILE window only: Adjust the window's contents so that the last (END 
line of the text file is at the bottom of the window 
DISP windows only: Scroll up through an array of structures (CONTROL ) 
PAGE UP 
DISP windows only: Scroll down through an array of structures (CONTROL ) 
CPAGE DOWN ) 


Editing data or selecting the active field 


The F9 function key makes the current field (the field that the cursor is pointing 
to) active. This has various effects, depending on the field. 


Use these 
To do this function keys 


FILE or DISASSEMBLY window: Set or clear a breakpoint 
CALLS window: Display the source to a listed function 
Any data-display window: Edit the contents of the current field 


DISP window: Open an additional DISP window to display a 
member that is an array, structure, or pointer 


a 
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Basic Information 
About C Expressions 


Many of the debugger commands take C expressions as parameters. This al- 
lows the debugger to have a relatively small yet powerful instruction set. Be- 
cause C expressions can have side effects—that is, the evaluation of some 
types of expressions can affect existing values—you can use the same com- 
mand to display or to change a value. This reduces the number of commands 
in the command set. 


This chapter contains basic information that you'll need to know in order to use 
C expressions as debugger command parameters. 


Topic Page 
12.1 C Expressions for Assembly Language Programmers 12-2 
12.2 Using Expression Analysis in the Debugger 12-4 

Restrictions 12-4 
Additional features 12-4 
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12.1 C Expressions for Assembly Language Programmers 
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It’s not necessary for you to be an experienced C programmer in order to use 
the debugger. However, in order to use the debugger’s full capabilities, you 
should be familiar with the rules governing C expressions. You should obtain 
a copy of The C Programming Language (first or second edition) by Brian 
W. Kernighan and Dennis M. Ritchie, published by Prentice-Hall, Englewood 
Cliffs, New Jersey. This book is referred to in the C community, and in Texas 
Instruments documentation, as K&R. 


—————————=———o“—V6Vn SG SV SS a 0 — Oe] 


Note: 


A single value or symbol is a legal C expression. 


K&R contains a complete description of C expressions; to get you started, 
here’s asummary of the operators that you can use in expression parameters. 


() Reference operators 


—> indirect structure reference : direct structure reference 
[] array reference . indirection (unary) 
& address (unary) 


(_] Arithmetic operators 


+ addition (binary) — subtraction (binary) 
* multiplication / division 
% modulo — negation (unary) 


(type) typecast 


(_] Relational and logical operators 


> greater than >= greater than or equal to 
< less than <= less than or equal to 
== is equal to l= is not equal to 

&& — logical AND | logical OR 


| logical NOT (unary) 
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[J Increment and decrement operators 


++ increment —— decrement 


These unary operators can precede or follow a symbol. When the operator 
precedes a symbol, the symbol value is incremented/decremented before 
itis used in the expression; when the operator follows a symbol, the sym- 
bol value is incremented/decremented after it is used in the expression. 
Because these operators affect the symbol’s final value, they have side 
effects. 


[) Bitwise operators 


& bitwise AND | bitwise OR 
as bitwise exclusive-OR <<__ left shift 
>> right shift 7 1s complement (unary) 


(J Assignment operators 


= assignment += assignment with addition 

= assignment with subtraction /= assignment with division 

%= assignment with modulo &= assignment with bitwise AND 
N= assignment with bitwise XOR |= assignment with bitwise OR 
<<= assignment with left shift >>= assignment with right shift 


7 assignment with multiplication 
These operators support a shorthand version of the familiar binary expres- 


sions; for example, X = X + Y canbe written in C as X += Y. Because these 
operators affect a symbol’s final value, they have side effects. 
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12.2 Using Expression Analysis in the Debugger 


Restrictions 


Additional features 
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The debugger’s expression analysis is based on C expression analysis. This 
includes all mathematical, relational, pointer, and assignment operators. How- 
ever, there are a few limitations, as well as a few additional features not de- 
scribed in K&R C. 


The following restrictions apply to the debugger’s expression analysis fea- 
tures. 


L} 
L} 


The size of operator is not supported. 


The comma operator (,) is not supported (commas are used to separate 
parameter values for the debugger commands). 


Function calls and string constants are currently not supported in expres- 
sions. 


The debugger supports a limited number of type casts; the following forms 
are allowed: 


( basic type ) 

( basic type* ...) 

( [ structure/union/enum]_structure/union/enum tag ) 

( [ structure/union/enun]_ structure/union/enum tag * ... ) 


Note that you can use up to six *s in a cast. 


All floating-point operations are performed in double precision using stan- 
dard widening. (This is transparent.) Floats are represented in IEEE float- 
ing-point format. 


All registers can be referenced by name. The ’C3x’s extended-precision 
registers (RO—R7) are treated as integers. You can use the names FO—F7 
to access the registers as floating-point values. 


Void expressions are legal (treated like integers). 


The specification of variables and functions can be qualified with context 
information. Local variables (including local statics) can be referenced 
with the expression form: 


function name.local name 
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This expression format is useful for examining the automatic variables of a 
function that is not currently being executed. Unless the variable is static, 
however, the function must be somewhere in the current call stack. If you 
want to see local variables from the currently executing function, you need 
not use this form; you can simply specify the variable name (just as in your 
C source). 


File-scoped variables (such as statics or functions) can be referenced with 
the following expression form: 


filename.function name 
or filename.variable name 


This expression format is useful for accessing a file-scoped static variable 
(or function) that may share its name with variables in other files. 


In this expression, filename does not include the file extension; the de- 
bugger searches the object symbol table for any source filename that 
matches the input name, disregarding any extension. Thus, if the variable 
ABC is in file source.c, you can specify it as source.ABC. 


These expression forms can be combined into an expression of the form: 


filename.function name.variable name 


Any integral or void expression can be treated as a pointer and used with 
the indirection operator (*). Here are several examples of valid use of a 
pointer in an expression: 

*123 

*R5 

*(R2 + 123) 

(EXT) 

By default, the values are treated as integers (that is, these expressions 
point to integer values). 


Any expression can be typecast to a pointer to a specific type (overriding 
the default of pointing to an integer, as described above). 


Hint: You can use casting with the WA and DISP commands to display 
data in a desired format. 


For example, the expression: 
*(float *)10 


treats 10 as apointer to a floating-point value at location 10 in memory. In 
this case, the debugger fetches the contents of memory location 10 and 
treats the contents as a floating-point value. If you use this expression as a 
parameter for the DISP command, the debugger displays memory con- 
tents as an array of floating-point values within the DISP window, begin- 
ning with memory location 10 as array member [0]. 
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Note how the first expression differs from the expression: 

(float) *10 

In this case, the debugger fetches an integer from address 10 and con- 
verts the integer to a floating-point value. 

You can also typecast to user-defined types such as structures. For exam- 
ple, in the expression: 

((struct STR *)10)->field 


the debugger treats memory location 10 as a pointer to a structure of type 
STR (assuming that a structure is at address 10) and accesses a field from 
that structure. 
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Specifications for Your Target 
System’s Connection to the Emulator 


This appendix contains information about connecting your target system with 
the emulator. 


Topic Page 


A.1_ Designing Your Target System’s A-2 

Emulator Connector (12-Pin Header) 
A.2 Buffering Signals Between the Emulator and the Target System A-3 
A-4 


A-6 


A.3 Buffer Delays 
A.4_ Mechanical Dimensions for the 12-Pin Emulator Connector 
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Designing Your Target System's Emulator Connector (12-Pin Header) 


A.1 Designing Your Target System’s Emulator Connector (12-Pin Header) 


The ’C3x uses a revolutionary technology to allow complete emulation via a 
serial scan path of the ’C3x. To perform realtime emulation, your target sys- 
tem must have a 12-pin header (2 rows of 6 pins) with the connections that 
are shown in Figure A-1. 


To use the target cable, supply the signals shown in Figure A—1 to a 12-pin 
header (two rows of six pins) with pin 8 cut out to provide keying. 


Figure A—1. 12-Pin Header Signals and Header Dimensions 


GND 
GND 
GND 
no pin (key) 
GND 
GND 


Header Dimensions: 

Pin-to-pin spacing, 0.100 in. (X,Y) 
Pin width, 0.025-in. square post 
Pin length, 0.235-in. nominal 


Use a BergStik II header or 
equivalent. 


Tt These signals should always be pulled up with separate 20-kQ resistors to +5 volts on the ’C3x. 


Table A—1.12-Pin Header Signal Description and Pin Numbers 


Signal 
EMUO 
EMU1 

EMU2 
EMU3 
H3 

PD 


Description 
Emulation pin 0 
Emulation pin 1 
Emulation pin 2 
Emulation pin 3 
’C3x H3 


°C30 
Pin Number 


F14 
E15 
F13 
E14 
Al 


°C31 
Pin Number 


124 
125 
126 
123 
82 


Presence detect. Indicates that the cable is connected and tar- 
get system is powered up. PD should be tied to +5 volts in the 


target system. 


Although you can use other headers, recommended parts include: 


straight header, unshrouded 


right-angle header, unshrouded 


right-angle header, 4-wall 


shrouded 


DuPont Connector Systems 
part number 67996—112 


DuPont Connector Systems 
part number 68405—112 


AMP, Incorporated 


part number 103167-3 


or part number 103166—4 


Buffering Signals Between the Emulator and the Target System 


A.2 Buffering Signals Between the Emulator and the Target System 


It is extremely important to provide high-quality signals between the emulator 
and the ’C3x on the target system. In many cases, the signal must be buffered 
to produce a high-quality signal. The need for signal buffering and placement 
of the emulation header can be divided into 3 categories: 


_} No signal buffering. In this situation, the distance between the header 
and the ’C3x should be no more than 2 inches. 


L$ to 2 inches—>| 


EMUO, EMU1, EMU2 


H3, EMU3 


(_] Buffered transmission signals. In this situation, the distance between 
the emulation header and the ’C3x is greater than 2 inches but less than 
6 inches. The transmission signals—H3 and EMU3—are buffered through 
the same package. 


— 2to6 inches——— 
3 


EMUO, EMU1, EMU2 


_] All signals buffered. The distance between the emulation header and the 
’C8x is greater than 6 inches but less than 12 inches. All ’C3x emulation 
signals—EMUO, EMU1, EMU2, and EMU3—are buffered through the 
same package. 


}+ 6 to 12 inches ———————> 


EMUO, EMU1, EMU2 


H3, EMU3 


Specifications for Your Target System’s Connection to the Emulator A-3 


Buffer Delays 


A.3 Buffer Delays 


The emulator is designed to support a TMS320C8x with H3 clock periods 
down to 40 ns. Table A—2 lists the maximum buffer delay for various H3 peri- 
ods. The buffer is noninverting. 


Table A—2. Maximum Buffer Delays 


H3 Period Maximum Buffer Delay 
60 ns 8ns 
50 ns 6 ns 
40 ns 4ns 


The distance between the ’C3x and the buffers depends on the printed-wire- 
board layout and loading on H3. However, Texas Instruments suggests that 
the distance be as short as possible and less than 4 inches. 


When you buffer H3, don’t place another device between the buffer output and 
the header (see Figure A-2). Connecting another device to this signal could 
cause false triggering of the device due to cable reflections. 


Figure A—2. H3 Buffer Restrictions 


Don't connect any devices be- 
tween the buffered H3 output 
and the header! 
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Buffer Delays 


Figure A-3 shows a portion of logic in the emulator pod. Note that 33-Q resis- 
tors are added to EMU0, EMU1, and EMU2; this minimizes cable reflections. 


Figure A—3. Emulator Pod Interface 


EMU1 (pin 1) 
EMUO (pin 3) 
EML2 (pin 5) 
EMU (pin 9) 
H3 (pin 11) 
PD (+5 V, pin 7) 


GND (pins 2, 4, 6, 10, 12) 


no pin (key, pin 8) 
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Mechanical Dimensions for the 12-Pin Emulator Connector 


A.4 Mechanical Dimensions for the 12-Pin Emulator Connector 


The ’C3x emulator target cable consists of a 3-foot section of jacketed cable, 
an active cable pod, and a short section of jacketed cable that connects to the 
target system. The overall cable length is approximately 3 feet,10 inches. 
Figure A—4 and Figure A-5 show the mechanical dimensions for the target 
cable pod and short cable. Note that the pin-to-pin spacing on the connector 
is 0.100 inches in both the X and Y planes. The cable pod box is nonconductive 
plastic with 4 recessed metal screws. 


Figure A-4. Pod/Connector Dimensions 


Please refer to Figure A—5. 
Note: All dimensions are in inches and are nominal dimensions, unless otherwise specified. 


Mechanical Dimensions for the 12-Pin Emulator Connector 


Figure A—5. 12-Pin Connector Dimensions 


or 


key, pin 8 


.70 


pin 1,3,5,7,9,11 | _ pin 2,4,6,8,10,12 


Note: All dimensions are in inches and are nominal dimensions, unless otherwise specified. 
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Constraints When Using the Emulator 


This appendix covers constraints concerning cache control when you are us- 
ing certain commands and restraints for software breakpoint and execution 
commands. This information applies only when you are using the debugger 
with the emulator. 


Topic Page 
B.1 Cache Interaction With Software Breakpoint Commands B-2 
B.2 Cache Control for Memory Commands B-3 
B.3 Command Constraints B-4 

Software breakpoint constraints B-4 
Single-step constraints with repeated instructions B-5 
Constraints imposed when emulator is reset B-5 


B-1 


Cache Interaction With Software Breakpoint Commands 


B.1 Cache Interaction With Software Breakpoint Commands 


This section explains how cache control works with the software breakpoint 
commands as discussed in Chapter 8. 
(_} BA command 


When the breakpoint address equals a cache instruction address, the 
cache p-flags are modified according to the following conditions: 


Cache Control 
Cache Enable Cache Freeze Description 
0 0 Place SWI in memory, no cache modification. 
0 1 Place SWI in memory, no cache modification. 


1 0 Place SWI in memory. If breakpoint address equals 
cache address and p-flag is set, the p-flag clears at 
the corresponding cache address. 


1 1 Place SWI in memory. 


Clearing the flag in the third case ensures that the SWI will always be 
executed, whether from cache or memory. 


(_] BD and BR commands 


When the breakpoint address equals a cache instruction address, the 
cache p-flags are modified according to the following conditions: 


Cache Control 


Cache Enable Cache Freeze Description 
0 0 Restores instruction to memory, no cache modifica- 
tion. 
0 1 Restores instruction to memory, no cache modifica- 
tion. 
1 0 Restores instruction to memory. If breakpoint ad- 


dress equals cache address and p-flag is set, the p- 
flag clears at the corresponding cache address. 


1 1 Restores instruction in memory. 
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Cache Control for Memory Commands 


B.2 Cache Control for Memory Commands 


This section explains how the cache control works with the memory modifica- 
tion commands discussed in Chapter 5. 


When amemory modify address is equal to acache control address, the cache 
p-flags are modified according to the following conditions: 


Cache Enable 


0 
0 
1 
1 


Cache Freeze 


0 
1 
0 
1 


Description 
No cache modification. 
No cache modification. 
Clears p-flag. 


No cache modification. 


Clearing the p-flag in the third case ensures that the emulator executes the 


most current instruction. 
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Command Constraints 


B.3 Command Constraints 


The following section discusses constraints that apply to software breakpoint 
and run commands and gives a correct (valid) and an incorrect (not valid) pro- 
gramming example for each rule. 


This section also describes constraints imposed when the target system is in 
a reset condition. 
Software breakpoint constraints 


(_] There must be a minimum of three instructions between a delayed 
branch and a breakpoint. 


Valid Not Valid 
BRD TEST BRD TEST 
LDI 0, RO LDI 0, RO 
LDI 1,R1 > LDI 1,R1 
LDI 2 Re EDI 2 Re 
> LDI 3,R3 LDI 3,R3 


(_} Do notplace a breakpoint on the repeat single instruction or the instruc- 
tion to be repeated. 


Valid Not Valid 
RPTS 5 > RPTS 5 
LDI 0,RO > LDI 0,RO 
> LDI 1,R1 LDI 1,R1 


_] Do not place a breakpoint on the last instruction of a repeat block. 


Valid Not Valid 
RPTB TEST RPTB TEST 
LDI 0, RO LDI 0, RO 
> LDI 1,R1 EDI 1,R1 
TEST: LDi 2,R2 > TEST: LDI 2,R2 
> LDI 3,R3 LDI 3,R3 
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Command Constraints 


Single-step constraints with repeated instructions 


The repeat single (RPTS) instruction is an indivisible instruction and cannot 
be single-stepped. However, the RPTS instruction can be replaced with the 
repeat block (RPTB) instruction with a block size of one. 


Example 7: RPTS 10 
STI RO, *ARO++ 
Example 2: LDI 10,RC 
RTPB ONE 
ONE: STI RO, *ARO++ 


Both instruction sequence examples perform the same function. However, the 
second example can be single-stepped to trace the execution. 


Constraints imposed when emulator is reset 


When the target system is in the reset condition or when the ’C3x RESET pin 
is held low, the emulator can still read and write to target memory. Under this 
condition, the ‘C3x memory interface signals will become active. This may 
cause problems in systems that use the ’C3x RESET signal to put the memory 
interface in a 3-state condition. 


The ’C3x HOLD signal should be used to put the primary bus in a 3-state condi- 
tion. Ifthe expansion bus is required to remain in the 3-state condition, it cannot 
be put in a 3-state condition with the HOLD signal and should not be accessed 
when the ’C3x is in the reset state. 
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Troubleshooting When Using the Emulator 


This appendix answers frequently asked questions about the ’C3x emulator. 
For other questions about the emulator, call the DSP hotline at (713) 
274-2320. 


Q Why does the CLK register on my emulator always read 0? 


A TheCLK register is updated only by the RUNB (run benchmark) command 
(described on page 6-19). Other run commands set the CLK register to 0. 


Note: CLK Register Operation 


The 'C3x emulator CLK register operates differently than the CLK register 
for the ’C3x simulator. 


Q Can | get a pipeline status with my ’‘C3x emulator? 


A No. The emulator does not provide a pipeline status, because it halts only 
on instruction boundaries with the pipeline flushed. All instructions in the 
pipeline are guaranteed to be executed when the emulator issues a halt 
command to the ’C3x. 


Q | have executed the RESET command on my ’C3x emulator and at- 
tempted to run code. Why does the PC remain unchanged and still contain 
my RESET vector? 


A The’C3x device RESET signal is still at a logic 0. If you attempt to execute 
code, the PC register remains unchanged, and the SP register incre- 
ments. If you are using the application board, you must execute the 
emurst.exe file in order to take the 'C3x device RESET signal to a logic 1. 
If you are operating the emulator with your own target system, you must 
set the 'C3x device’s reset signal to a logic 1 to run code. 
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Q 
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© 


© 
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Does the ’C3x emulator show the last instruction executed or the next 
instruction to be executed? 


The emulator always shows the next instruction to be executed. All pre- 
vious instructions have completed before the emulator halts. 


Can | display or directly modify the ‘C3x cache? 


No. The cache is not accessible. However, the emulator keeps the pro- 
gram memory and cache coherent by manipulating the appropriate p- 
flags. 


Does DMA continue to operate when the ’C3x is halted? 


No. The DMA finishes its current memory cycle and halts. The DMA picks 
up where it left off when the processor starts running again. 


When the ’C3x halts, can other devices gain access to the parallel bus? 


Yes. When the 'C3x is halted, the HOLD and HOLDA signals continue to 
function. If you attempt to perform an external memory access via the 
emulator while the ’C3x is in the HOLD state, you may get a memory error 
or reduced emulator performance. The emulator always attempts to gain 
access to the external memory bus. When an attempt fails, the emulator 
begins a retry and time-out sequence. 
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Q I cannot determine or find the I/O address requirements of my PC in any 


of my product or PC documentation. How can | figure out where to map 
my ’C3x emulator? 


A The following procedure works but should be used only as a last resort be- 


cause it may cause I/O bus conflicts if the emulator and another card are 
mapped to the same I/O address. 


Find an open location in the PC I/O map: 


Set the emulator’s I/O 
switches and the init.cmd file 
to the default configuration. 


Reboot the PC to execute 
the emulator. 


Did the PC Set the emulator’s I/O 
boot and operate switches and the init.cmd file 
correctly? to the next configuration. 


You have found a valid I/O 
configuration area. 


Troubleshooting When Using the Emulator C-3 


Troubleshooting When Using the Emulator 


C-4 


The following questions and answers pertain to the interfacing of the 
*C3x emulator and the ’C3x application board or to the modification of 
the ’C3x application board. 


Q Ihave purchased the ‘C3x XDS1000 Development Environment. Must the 
‘C3x emulator and the ’C3x application board be installed in the same host 
system? 


A No. The emulator and the application board may be in different host sys- 
tems. In fact, if you are trying to debug code on the application board and 
the host at the same time, itis preferable to use two systems because DOS 
is not a multitasking environment. 


Q |have written a small loader program for the ’C3x application board to load 
data from the host through the dual port RAM. How can | start to execute 
the program on the application board and test my host program? 


A There are two methods; 


HM Perform an xreset command followed by an emurst command to dis- 
able the emulator and reset the application board. If your loader pro- 
gram is initiated from reset, this method will work. 


M@ Thesecond and preferred method is to load the debugger, enter a RE- 
SET command to initiate the debugger, and then enter a RUNF com- 
mand. The RUNF command will start to execute the ‘C3x at the cur- 
rent address of the program counter. 


To suspend the debugger interface, use the SYSTEM command. The 
SYSTEM command allows you to enter operating-system com- 
mands. To re-enter the debugger, type exit. Now that you are back in 
the debugger interface, you can use the HALT command to resume 
the program from the point of suspension, or you can type RESET to 
start over. 


Q When accessing the dual port RAM on the 'C3x application board via the 
‘C3x emulator, | read trash on the upper bits of the data bus. Why? 


A Thedual port RAM on the application board is only 8 bits wide. The upper 
24 bits of the data bus are left floating. Thus, their value is undetermined 
on read cycles. The emulator does not mask off the unused data bits be- 
fore displaying memory. 
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Q Ihave purchased the ‘C3x XDS1000 Development Environment. Does 
this system require 1.5 or 3 slots in my PC? 


A The development environment requires 3 slots in your PC. However, if the 
emulator is installed in front of the application board, then half of a slot is 
open between the two boards. 


1/2 Open Slot 


’C3x application board *C3x emulator board 


Top View 


Q How can! change the ’C3x vectors on the ’C3x application board? 


A There are two methods: 
HM One way is to replace the supplied EPROMs with your own EPROMs. 


HM Thesecond way is to set the applications board MSWAP bit to a logic 
1. This causes the EPROM and SRAM to swap address ranges. 
Modify the SRAM to set up a different set of vectors. 


Note: 
[_] The MSWAP bit is located at address 805FF7h, bit 7. 


__] The MSWAP bitis cleared to a logic 0 when the application board is reset 
via the emurst.exe. 


[_| The emulator does not clear the MSWAP bit when executing the RESET 
command. 


Q | want to write m y own resetvinitialization routine for the ‘C3x application 
board. Are there any special requirements ? 


A Yes. Set the memory ports to use external wait states and set the block 
size to the default of 256 words. The file c30exam.asm, included with the 
application board software package, contains an example setup. 
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Q lam using the examples in the TMS320 Family Floating-Point DSP Opti- 


mizing C Compiler User’s Guide to write C code for the ’C3x application 
board. When | try to load my program using the ‘C3x emulator, | get a re- 
served peripheral error message. 


The mostlikely problem is that the memory map used in the TMS320 Fam- 
ily Floating-Point DSP Optimizing C Compiler User’s Guide is not compat- 
ible with the applications board. Included with the application board is a 
memory map template for the program c30exam.asm. The template file- 
name is c30exam.cmd; use it as an example and modify it to meet your 
needs. 


| get the error message CANNOT INITIALIZE TARGET SYSTEM when | 
try to execute emu3x or evm3x. 


The port address of the emulator or EVM was not been specified correctly 
when you started the task. Verify the switch settings in your hardware (re- 
fer to your installation guide) and then verify that you have used the correct 
port address option when you invoked the debugger. (Also check to see 
whether you specified a different address with the environment variable 
D_OPTIONS.) 


If you continue to have the error, verify that your target system is powered 
up and that the emulator connector is properly connected. If you are bring- 
ing up the target hardware for the first time, verify that the correct signals 
are active from the ’C3x to the emulator connector. You should check to 
see if the EMU4/SHZ pin on the ’C3x device is pulled high. 
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What the Debugger Does 
During Invocation 


In some circumstances, you may find it helpful to know the steps that the de- 
bugger goes through during the invocation process. These are the steps, in 
order, that the debugger performs when you invoke it. (For more information 
on the environment variables mentioned below, refer to the appropriate instal- 
lation guide.) 


1) Reads options from the command line. 


2) Reads any information specified with the DLOPTIONS environment vari- 
able. 


3) Reads information from the D_DIR and D_SRC environment variables. 


4) Looks for the init.clr screen configuration file. 


(The debugger searches for the screen configuration file in directories 
named with D_DIR.) 


5) Initializes the debugger screen and windows but initially displays only the 
COMMAND window. 


6) Finds the batch file that defines your memory map by searching in directo- 
ries named with D_DIR. The debugger expects this file to set up the 
memory map and follows these steps to look for the batch file: 


a) When you invoke the debugger, it checks to see if you’ve used the -t 
debugger option. If it finds the -t option, the debugger reads and 
executes the specified file. 


b) Ifyou don’t use the -+t option, the debugger looks for the default initial- 
ization batch file called init.cmd. lf the debugger finds this file, it reads 
and executes the commands. 


7) Loads any object filenames specified with D_OPTIONS or specified on the 
command line during invocation. 


8) Determines the initial mode (auto, assembly, or mixed) and displays the 
appropriate windows on the screen. 


At this point, the debugger is ready to process any commands that you enter. 
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Debugger Messages 


This appendix contains an alphabetical listing of the progress and error mes- 
sages that the debugger might display inthe COMMAND window display area. 
Each message contains both a description of the situation that causes the 
message and an action to take if the message indicates a problem or error. 


Topic Page 
E.1 Associating Sound With Error Messages E-2 
E.2 Alphabetical Summary of Debugger Messages E-2 
E.3 Additional Instructions for Expression Errors E-20 
E.4 Additional Instructions for Hardware Errors E-20 
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Associating Sound With Error Messages / Alphabetical Summary of Debugger Messages 


E.1 Associating Sound With Error Messages 


You can associate a beeping sound with the display of error messages. To do 
this, use the SOUND command. The format for this command is: 


sound {on | off} 


By default, no beep is associated with error messages (SOUND OFF). The 
beep is helpful if the COMMAND window is hidden behind other windows. 
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E-2 


‘|’ expected 


Description This is an expression error—it means that the parameter con- 
tained an opening “[” but didn’t contain a closing “]”. 


Action See Section E.3 (page E-20). 


‘)’ expected 


Description This is an expression error—it means that the parameter con- 
tained an opening “(” but didn’t contain a closing “)”. 


Action See Section E.3 (page E-20). 


Aborted by user 


Description The debugger halted a long COMMAND display listing (from 
WHATIS, DIR, ML, or BL) because you pressed the key. 


Action None required; this is normal debugger behavior. 
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Breakpoint already exists at address 


Description 


Action 


During single-step execution, the debugger attempted to set 
a breakpoint where one already existed. (This isn’t necessari- 
ly a breakpoint that you set—it may have been an internal 
breakpoint that was used for single-stepping). 


None should be required; you may want to reset the program 
entry point (RESTART) and re-enter the single-step com- 
mand. 


Breakpoint table full 


Description 


Action 


200 breakpoints are already set, and there was an attempt to 
set another. The maximum limit of 200 breakpoints includes 
internal breakpoints that the debugger may set for single- 
stepping. Under normal conditions, this should not be a prob- 
lem; it is rarely necessary to set this many breakpoints. 


Enter a BL command to see where software breakpoints are 
set in your program. Use the BR command to delete all soft- 
ware breakpoints, or use the BD command to delete individu- 
al software breakpoints. 


Cannot allocate host memory 


Description 


Action 


This is a fatal error—it means that the debugger is running out 
of memory. 


You might try invoking the debugger with the —v option so that 
fewer symbols may be loaded. Or you might want to relink 
your program and link in fewer modules at a time. 


Cannot allocate system memory 


Description 


Action 


This is a fatal error—it means that the debugger is running out 
of memory. 


You might try invoking the debugger with the —v option so that 
fewer symbols may be loaded. Or you might want to relink 
your program and link in fewer modules at a time. 
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Corrupt call stack 


Description 


Action 


The debugger tried to update the CALLS window and 
couldn't. This may be because a function was called that 
didn’t return. Or it could be that the program stack was over- 
written in target memory. Another reason you may have this 
message is that you are debugging code that has optimiza- 
tion enabled (for example, you did not use the —g compile 
switch); if this is the case, ignore this message—code execu- 
tion is not affected. 


If your program called a function that didn’t return, then this is 
normal behavior (as long as you intended for the function not 
to return). Otherwise, you may be overwriting program 
memory. 


Cannot change directory 


Description 


Action 


The directory name specified with the CD command either 
doesn't exist or is not in the current or auxiliary directories. 


Check the directory name that you specified. If this is really 
the directory that you want, re-enter the CD command and 
specify the entire pathname for that directory (for example, 
specify C:\c3xhll, not just c3xhll). 


Cannot edit field 


Description 


Action 


Expressions that are displayed in the WATCH window cannot 
be edited. 


If you attempted to edit an expression in the WATCH window, 
you may have actually wanted to change the value of a sym- 
bol or register used in the expression. Use the ? or EVAL com- 
mand to edit the actual symbol or register. The expression 
value will automatically be updated. 


Cannot find/open initialization file 


Description 


Action 


The debugger can’t find the init.cmd file. 


Be sure that init.cmd is in the appropriate directory. If it isn’t, 
copy it from the debugger product diskette. Ifthe file is already 
in the correct directory, verify that the D_DIR environment 
variable is set up to identify the directory. See Setting Up the 
Debugger Environment in the appropriate installation guide. 
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Cannot halt the processor 


Description This is a fatal error—for some reason, pressing didn’t 
halt program execution. 


Action Exit the debugger. Invoke emurst (emulator only), then invoke 
the debugger again. 


Cannot map into reserved memory: ? 


Description The debugger tried to access unconfigured/reserved/nonex- 
istent memory. 


Action Remap the reserved memory accesses. 


Cannot map port address 


Description You attempted to do a connect/disconnect on an illegal port 
address. 


Action Verify that the address you specified is a valid primary bus, 
expansion bus, or serial port address. 


Cannot open config file 


Description The SCONFIG command can't find the screen-customization 
file that you specified. 


Action Be sure that the filename was typed correctly. If it wasn't, re- 
enter the command with the correct name. If it was, re-enter 
the command and specify full path information with the file- 
name. 


Cannot open “filename” 


Description The debugger attempted to show filename in the FILE win- 
dow but could not find the file. 


Action Be sure that the file exists as named. If it does, enter the USE 
command to identify the file’s directory. 


Cannot open object file: “filename” 
Description The file specified with the LOAD, SLOAD, or RELOAD com- 
mand is not an object file that the debugger can load. 


Action Be sure that you’re loading an actual object file. Be sure that 
the file was linked (you may wantto run cl30 again to create an 
executable object file). 
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Cannot open new window 


Description 


Action 


A maximum of 127 windows can be open at once. The last re- 
quest to open a window would have made 128, which isn’t 
possible. 


Close any unnecessary windows. Windows that can be 
closed include WATCH, CALLS, DISP, and additional 
MEMORY windows. To close the WATCH window, enter WD. 
To close the CALLS, DISP, ora MEMORY window, make the 
desired window active and press (4). 


Cannot read processor status 


Description 


Action 


This is a fatal error—for some reason, pressing didn’t 
halt program execution. 


Exit the debugger. Invoke emurst (emulator only), then invoke 
the debugger again. 


Cannot reset the processor 


Description 


Action 


This is a fatal error—for some reason, pressing didn’t 
halt program execution. 


Exit the debugger. Invoke emurst (emulator only), then invoke 
the debugger again. 


Cannot restart processor 


Description 


Action 


If a program doesn’t have an entry point, then RESTART 
won't reset the PC to the program entry point. 


Don’t use RESTART if your program doesn’t have an explicit 
entry point. 


Cannot set/verify breakpoint at address 


Description 


Action 


Either you attempted to set a breakpoint in read-only or pro- 
tected memory, or there are hardware problems with the tar- 
get system or EVM. This may also happen when you enable 
or disable on-chip memory while using breakpoints. 


Check your memory map. If the address that you wanted to 
breakpoint wasn’t in ROM, see Section E.4 (page E-20). 
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Cannot step 
Description There is a problem with the target system. 
Action See Section E.4 (page E-20). 


Cannot take address of register 


Description This is an expression error. C does not allow you to take the 
address of a register. 


Action See Section E.3 (page E-20). 


Command “cma” not found 
Description The debugger didn’t recognize the command that you typed. 


Action Re-enter the correct command. Refer to Chapter 11 or the 
Quick Reference Card for a list of valid debugger commands. 


Command timed out, emulator busy 
Description There is a problem with the target system. 
Action See Section E.4 (page E-20). 


Conflicting map range 


Description A block of memory specified with the MA command overlaps 
an existing memory map entry. Blocks cannot overlap. 


Action Use the ML command to list the existing memory map; this will 
help you find that existing block that the new block would 
overlap. If the existing block is not necessary, delete it with the 
MD command and re-enter the MA commana. If the existing 
block is necessary, re-enter the MA command with parame- 
ters that will not overlap the existing block. 


Emulator I/O address is invalid 


Description The debugger was invoked with the —p option, and an invalid 
port address was used. 


Action For valid port address values, refer to the TMS320C3x Emu- 
lator Installation Guide. 
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Error in expression 
Description This is an expression error. 


Action See Section E.3 (page E-20). 


Execution error 
Description There is a problem with the target system. 


Action See Section E.4 (page E-20). 


File already tied to port 


Description You attempted to connect to an address that already has a file 
connected to it. 


Action Connect the file to a mapped port that is not connected to a 
file. 


File already tied to this pin 


Description You attempted to connect an input file to an interrupt pin that 
already has a file connected to it. 


Action Use the PINC command to connect the file to another inter- 
rupt pin that is not connected to a file. 


File does not exist 
Description The port file could not be opened for reading. 


Action Be sure that the file exists as named. If it does, enter the USE 
command to identify the file’s directory. 


Files must be disconnected from ports 


Description You attempted to delete a memory map that has files con- 
nected to it. 


Action You must disconnect a port with the MI command before you 
can delete it from the memory map. 
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File not found 


Description The filename specified for the FILE command was not found 
in the current directory or any of the directories identified with 


D_SRC. 

Action Be sure that the filename was typed correctly. If it was, re-en- 
ter the FILE command and specify full path information with 
the filename. 


File not found : “filename” 


Description The filename specified for the LOAD, RELOAD, SLOAD, or 
TAKE command was not found in the current directory or any 
of the directories identified with D_SRC. 


Action Be sure that the filename was typed correctly. If it was, re-en- 
ter the command and specify full path information with the file- 
name. 


File too large (filename) 


Description You attempted to load a file that was more than 65,518 bytes 
long. 


Action Try loading the file without the symbol table (GSLOAD), or use 
cl30 to relink the program with fewer modules. 


Float not allowed 


Description This is an expression error—a floating-point value was used 
incorrectly. 


Action See Section E.3 (page E-20). 


Function required 


Description The parameter for the FUNC command mustbe the name of a 
function in the program that is loaded. 


Action Re-enter the FUNC command with a valid function name. 


Illegal addressing mode 
Description An illegal ’C3x addressing mode was encountered. 


Action Refer to the TMS320C3x User’s Guide for valid addressing 
modes. 
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Illegal cast 


Description This is an expression error—the expression parameter uses 
a cast that doesn’t meet the C language rules for casts. 


Action See Section E.3 (page E-20). 


Illegal control transfer instruction 


Description The instruction following a delayed branch/call instruction 
was modifying the program counter. 


Action Modify your source code. 


Illegal left hand side of assignment 


Description This is an expression error—the lefthand side of an assign- 
ment expression doesn’t meet C language assignment rules. 


Action See Section E.3 (page E-20). 


Illegal memory access 
Description Your program tried to access unmapped memory. 


Action Modify your source code. 


Illegal opcode 
Description An invalid ’C3x instruction was encountered. 


Action Modify your source code. 


Illegal operand of & 


Description This is an expression error—the expression attempts to take 
the address of an item that doesn’t have an address. 


Action See Section E.3 (page E-20). 


Illegal pointer math 


Description This is an expression error—some types of pointer math are 
not valid in C expressions. 


Action See Section E.3 (page E-20). 
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Illegal pointer subtraction 


Description This is an expression error—the expression attempts to use 
pointers in a way that is not valid. 


Action See Section E.3 (page E-20). 


Illegal structure reference 


Description This is an expression error—either the item being referenced 
as a structure is nota structure, or you are attempting to refer- 
ence a nonexistent portion of a structure. 


Action See Section E.3 (page E-20). 


Illegal use of structures 


Description This is an expression error—the expression parameter is not 
using structures according to the C language rules. 


Action See Section E.3 (page E-20). 


Illegal use of void expression 


Description This is an expression error—the expression parameter does 
not meet the C language rules. 


Action See Section E.3 (page E-20). 


Integer not allowed 


Description This is an expression error—the command did not accept an 
integer as a parameter. 


Action See Section E.3 (page E-20). 


Invalid address 
— Memory access outside valid range: address 


Description The debugger attempted to access memory at address, 
which is outside the memory map. 


Action Check your memory map to be sure that you access valid 
memory. 


Invalid argument 


Description One of the command parameters does not meet the require- 
ments for the command. 


Action Re-enter the command with valid parameters. Refer to the 
appropriate command description in Chapter 11. 
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Invalid attribute name 


Description 


Action 


The COLOR and SCOLOR commands accept a specific set 
of area names for their first parameter. The parameter en- 
tered did not match one of the valid attributes. 


Re-enter the COLOR or SCOLOR command with a valid area 
name parameter. Valid area names are listed in Table 9-2 
(page 9-3). 


Invalid color name 


Description 


Action 


The COLOR and SCOLOR commands accept a specific set 
of color attributes as parameters. The parameter entered did 
not match one of the valid attributes. 


Re-enter the COLOR or SCOLOR commandwith a valid color 
parameter. Valid color attributes are listed in Table 9-1 (page 
9-2). 


Invalid memory attribute 


Description 


Action 


The third parameter of the MA command specifies the type, or 
attribute, of the block of memory that MA adds to the memory 
map. The parameter entered did not match one of the valid 
attributes. 


Re-enter the MA command. Use one of the following valid pa- 
rameters to identify the memory type: 


R, ROM, READONLY (read-only memory) 


W, WOM, WRITEONLY write-only memory) 


( 
R|W, RAM (read/write memory) 
PROTECT (no-access memory) 
OPORT (I/O memory) 
IPORT (I/O memory) 
IOPORT (I/O memory) 
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Invalid object file 


Description 


Action 


Either the file specified with the LOAD, SLOAD, or RELOAD 
command is not an object file that the debugger can load, or it 
has been corrupted. 


Be sure that you’re loading an actual object file. Be sure that 
the file was linked (you may wantto run cl30 again to create an 
executable object file). If the file you attempted to load was a 
valid executable object file, then it was probably corrupted; re- 
compile, assemble, and link with cl30. 


Invalid watch delete 


Description 


Action 


The debugger can’t delete the parameter supplied with the 
WD command. Usually, this is because the watch index 
doesn’t exist or because a symbol name was typed in instead 
of a watch index. 


Re-enter the WD command. Be sure to specify the watch in- 
dex that matches the item you’d like to delete (this is the num- 
ber in the left column of the WATCH window). Remember, you 
can’t delete items symbolically—you must delete them by 
number. 


Invalid window position 


Description 


Action 


The debugger can’t move the active window to the XY posi- 
tion specified with the MOVE command. Either the XY param- 
eters are not within the screen limits, or the active window 
may be too large to move to the desired position. 


[.] You can use the mouse to move the window. 


__] If you don’t have a mouse, enter the MOVE command 
without parameters; then use the arrow keys to move the 
window. When you’re finished, you must press or 
@). 


(_] Ifyou prefer to use the MOVE command with parameters, 
the minimum XY position is 0,1; the maximum position 
depends on which screen size you're using. 
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Invalid window size 


Description The width and length specified with the SIZE or MOVE com- 
mand may be too large or too small. If valid width and length 
were specified, then the active window is already at the far 
right or bottom of the screen and so cannot be made larger. 


Action [.} You can use the mouse to size the window. 


[_] If you don’t have a mouse, enter the SIZE command with- 
out parameters; then use the arrow keys to move the win- 
dow. When you're finished, you must press or @). 


_] If you prefer to use the SIZE command with parameters, 
the minimum size is 4 by 3; the maximum size depends 
on which screen size you’re using. 


Load aborted 
Description This message always follows another message. 


Action Refer to the message that preceded Load aborted. 


Lost power (or cable disconnected) 


Description Either the target cable is disconnected, or the target system is 
faulty. 


Action Check the target cable connections. If the target seems to be 
connected correctly, see Section E.4 (page E-20). 


Lost processor clock 


Description Either the target cable is disconnected, or the target system is 
faulty. 


Action Check the target cable connections. If the target seems to be 
connected correctly, see Section E.4 (page E-20). 
Lval required 


Description This is an expression error—an assignment expression was 
entered that requires a legal left-hand side. 


Action See Section E.3 (page E-20). 
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Memory access error at address 


Description Either the processor is receiving a bus fault, or there are prob- 
lems with target system memory. 


Action See Section E.4 (page E-20). 


Memory map table full 


Description Too many blocks have been added to the memory map. This 
rarely happens unless blocks are added word by word (which 
is inadvisable). 


Action Stop adding blocks to the memory map. Consolidate any ad- 
jacent blocks that have the same memory attributes. 


Name “name” not found 
Description The command cannot find the object named name. 


Action _] If nameis asymbol, be sure that it was typed correctly. If it 
wasn’t, re-enter the command with the correct name. If it 
was, then be sure that the associated object file is loaded. 


_] If name was some other type of parameter, refer to the 
command's description for a list of valid parameters. 


Nesting of repeats cannot exceed 100 


Description The debugger cannot simulate more than 100 levels of repeat 
nesting in an input data file. If this happens, the debugger dis- 
connects the input file from the pin. 


Action Correct the input file so that the data does not include nesting 
repetition exceeding 100 levels. Use the PINC command to 
reconnect the input file to the desired pin. 


No file connected to this pin 


Description You tried to disconnect the input file from a pin that was not 
previously connected to that pin. 


Action Use the PINL command to list all of the pins and the files con- 
nected to them. Use the PIND command to re-enter the cor- 
rect pinname and filename. 
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Nonrepeatable instruction 


Description The instruction following the RPT instruction is not a repeat- 
able instruction. 


Action Modify your code. 


Pinname not valid for this chip 
Description You attempted to connect or disconnect an input file to an 
invalid interrupt pin. 


Action Either reconnect the input file to an unused interrupt pin 
(INTO, INT1, INT2, or INT3), or disconnect the input file from 
the interrupt pin. 


Pointer not allowed 
Description This is an expression error. 
Action See Section E.3 (page E-20). 


Processor is already running 


Description One of the RUN commands was entered while the debugger 
was running free from the target system. 


Action Enter the HALT command to stop the free run, then re-enter 
the desired RUN command. 


Read not allowed for port 


Description You attempted to connect a file for input operation to an ad- 
dress that is not configured for read. 


Action Remap the port of correct the access in your source code. 


Register access error 


Description Either the processor is receiving a bus fault, or there are prob- 
lems with target-system memory. 


Action See Section E.4 (page E-20). 
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Specified map not found 


Description The MD command was entered with an address or block that 
is not in the memory map. 


Action Use the ML command to verify the current memory map. 
When using MD, you can specify only the first address of a 
defined block. 


Structure member not found 


Description This is an expression error—an expression references a non- 
existent structure member. 


Action See Section E.3 (page E-20). 


Structure member name required 


Description This is an expression error—a symbol name followed by a pe- 
riod but no member name. 


Action See Section E.3 (page E-20). 


Structure not allowed 


Description This is an expression error—the expression is attempting an 
operation that cannot be performed on a structure. 


Action See Section E.3 (page E-20). 


Syntax error at line number 


Description The debugger will not simulate interrupts from the input data 
file and disconnects the input file. 


Action Correct the syntax in the input data file. Reconnect the input 
file to the pin using the PINC command. 
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Take file stack too deep 


Description 


Action 


Batch files can be nested up to 10 levels deep. Batch files can 
call other batch files, which can call other batch files, and so 
on. Apparently, the batch file that you are TAKEing calls batch 
files that are nested more than 10 levels deep. 


Edit the batch file that caused the error. Instead of calling 
another batch file from within the offending file, you may want 
to copy the contents of the second file into the first. This will 
remove a level of nesting. 


Too few instruction words in RPTB 


Description 


Action 


The length of the repeat block was less than three instruction 
words. 


Modify your code. 


Too many breakpoints 


Description 


Action 


200 breakpoints are already set, and there was an attempt to 
set another. Note that the maximum limit of 200 breakpoints 
includes internal breakpoints that the debugger may set for 
single-stepping. Under normal conditions, this should not be 
a problem; it is rarely necessary to set this many breakpoints. 


Enter a BL command to see where you have breakpoints set 
in your program. Use the BR command to delete all break- 
points, or use the BD command to delete individual software 
breakpoints. 


Too many paths 


Description 


Action 


More than 20 paths have been specified cumulatively with the 
USE command, D_SRC environment variable, and —i debug- 
ger option. 


Don’t enter the USE command before entering another com- 
mand that has a filename parameter. Instead, enter the se- 
cond command and specify full path information for the file- 
name. 
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Undeclared port address 


Description 


Action 


User halt 


Description 


Action 


You attempted to do a connect/disconnect on an address that 
isn’t declared as a port. 


Verify the address of the port to be connected or discon- 
nected. 


The debugger halted program execution because you 
pressed the key. 


None required; this is normal debugger behavior. 


Window not found 


Description 


Action 


The parameter supplied for the WIN command is not a valid 
window name. 


Re-enter the WIN command. Remember that window names 
must be typed in uppercase letters. Here are the valid window 
names; the bold letters show the smallest acceptable ab- 
breviations: 


CALLS CPU DISP 
COMMAND DISASSEMBLY FILE 
MEMORY PROFILE WATCH 


Write not allowed for port 


Description 


Action 


You attempted to connect a file for output operation to an ad- 
dress that is not configured for write. 


Either change the ’C3x software to write to a port that is con- 
figured for write, or change the attributes of the port. 
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E.3 Additional Instructions for Expression Errors 


Whenever you receive an expression error, you should re-enter the command 
and edit the expression so that it follows the C language expression rules. If 
necessary, refer to a C language manual such as The C Programming Lan- 
guage by Brian W. Kernighan and Dennis M. Ritchie. 


E.4 Additional Instructions for Hardware Errors 


E-20 


If you continue to receive the messages that send you to this section, this indi- 
cates persistent hardware problems. 


[_] If a bus fault occurs, the emulator may not be able to access memory. 


[_] The ’C3x must be reset before you can use the emulator. Most target sys- 
tems reset the 'C3x at power-up; your target system may not be doing this. 
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active window: The window that is currently selected for moving, sizing, 
editing, closing, or some other function. 


aggregate type: AC data type such as a structure or array in which a vari- 
able is composed of multiple variables, called members. 


aliasing: A method of customizing debugger commands; aliasing provides 
a shorthand method for entering often-used command strings. 


ANSI C: A version of the C programming language that conforms to the C 
standards defined by the American National Standards Institute. 


assembly mode: A debugging mode that shows assembly language code 
in the DISASSEMBLY and doesn’t show the FILE window, no matter 
what type of code is currently running. 


autoexec.bat: A batch file that contains DOS commands for initializing your 
PC. 


auto mode: A context-sensitive debugging mode that automatically 
switches between showing assembly language code in _ the 
DISASSEMBLY window and C code in the FILE window, depending on 
what type of code is currently running. 


batch file: One of two different types of files. One type contains DOS com- 
mands for the PC to execute. A second type of batch file contains debug- 
ger commands for the debugger to execute. The PC doesn’t execute de- 
bugger batch files, and the debugger doesn’t execute PC batch files. 
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benchmarking: A type of program execution that allows you to track the 
number of CPU cycles consumed by a specific section of code. 


breakpoint: A point within your program where execution will halt because 
of a previous request from you. 


C: A high-level, general-purpose programming language useful for writing 
compilers and operating systems and for programming microproces- 
sors. 


CALLS window: A window that lists the functions called by your program. 


casting: A feature of C expressions that allows you to use one type of data 
as if it were a different type of data. 


children: Additional windows opened for aggregate types that are members 
of a parent aggregate type displayed in an existing DISP window. 


cl30: Ashell utility that invokes the TMS320 floating-point DSP compiler, as- 
sembler, and linker to create an executable object file version of your pro- 
gram. 


click: To press and release a mouse button without moving the mouse. 


CLK: A pseudoregister that shows the number of CPU cycles consumed 
during benchmarking. The value in CLK is valid only after you enter a 
RUNB command but before you enter another RUN command. 


code-display windows: Windows that show code, text files, or code-specif- 
ic information. This category includes the DISASSEMBLY, FILES, and 
CALLS windows. 


COFF: Common Object File Format. An implementation of the object file for- 
mat of the same name developed by AT&T. The TMS320 floating-point 
DSP compiler, assembler, and linker use and generate COFF files. 


commandline: The portion of the COMMAND window where you can enter 
commands. 


command-line cursor: A block-shaped cursor that identifies the current 
character position on the command line. 


COMMAND window: A window that provides an area for you to enter com- 
mands and for the debugger to echo command entry, show command 
output, and list progress or error messages. 
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CPUwindow: Awindow thatdisplays the contents of ’C3x on-chip registers, 
including the program counter, status register, A-file registers, and B-file 
registers. 


current-field cursor: Ascreen icon that identifies the current field in the ac- 
tive window. 


cursor: Aniconon the screen (such as a rectangle or a horizontal line) that 
is used as a pointing device. The cursor is usually under mouse or key- 
board control. 


data-display windows: Windows for observing and modifying various 
types of data. This category includes the MEMORY, CPU, DISP, and 
WATCH windows. 


D_DIR: An environment variable that identifies the directory containing the 
commands and files necessary for running the debugger. 


debugger: A window-oriented software interface that helps you to debug 
’°C8x programs running on a ‘C3x emulator, EVM, or simulator. 


disassembly: Assembly language code formed from the reverse-assembly 
of the contents of memory. 


DISASSEMBLY window: A window that displays the disassembly of 
memory contents. 


DISP window: A window that displays the members of an aggregate data 
type. 


display area: The portion of the COMMAND window where the debugger 
echoes command entry, shows command output, and lists progress or 
error messages. 


D_OPTIONS: Anenvironmentvariable that you can use for identifying often- 
used debugger options. 


drag: To move the mouse while pressing one of the mouse buttons. 


D_SRC: An environment variable that identifies directories containing pro- 
gram source files. 
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EGA: Enhanced Graphics Adaptor. An industry standard for video cards. 
EISA: Extended Industry Standard Architecture. A standard for PC buses. 


emulator: A debugging tool that is external to the target system and pro- 
vides direct control over the ’C3x processor that is on the target system. 


emurst: A utility that resets the emulator. 


environment variable: A special system symbol that the debugger uses for 
finding directories or obtaining debugger options. 


EVM: Evaluation Module. A development tool that lets you execute and de- 
bug applications programs by using the ’'C3x debugger. 


evmrst: A utility that resets the EVM. 


FILE window: A window that displays the contents of the current C code. 
The FILE window is intended primarily for displaying C code but can be 
used to display any text file. 


init.cmd: A batch file that contains debugger-initialization commands. If this 
file isn’t present when you first invoke the debugger, then all memory is 
invalid. 


initdb.bat: A batch file created to contain DOS commands to set up the de- 
bugger environment. 


/O switches: Hardware switches on the emulator or EVM board that identi- 
fy the PC I/O memory space used for emulator-debugger or EVM-debug- 
ger communications. 


ISA: /ndustry Standard Architecture. A subset of the EISA standard. 


memory map: A map of memory space that tells the debugger which areas 
of memory can and can’t be accessed. 
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MEMORY window: A window that displays the contents of memory. 


menubar: Arowof pulldown menu selections found at the top of the debug- 
ger display. 


mixed mode: Adebugging mode that simultaneously shows both assembly 
language code in the DISASSEMBLY window and C code in the FILE 
window. 


mouse cursor: A block-shaped cursor that tracks mouse movements over 
the entire display. 


PC: Personal computer or program counter, depending on the context and 
where it’s used in this book: 1) In installation instructions or information 
relating to hardware and boards, PC means Personal Computer (as in 
IBM PC). 2) In general debugger and program-related information, PC 
means Program Counter, which is the register that identifies the current 
statement in your program. 


point: To move the mouse cursor until it overlays the desired object on the 
screen. 


port address: The PC I/O memory space that the debugger uses for com- 
municating with the emulator or EVM. The port address is selected via 
switches on the emulator or EVM board and communicated to the debug- 
ger with the —p debugger option. 


pulldown menu: A command menu that is accessed by name or with the 
mouse from the menu bar at the top of the debugger display. 


scalartype: ACtypeinwhich the variable is a single variable, not composed 
of other variables. 


scrolling: A method of moving the contents of a window up, down, left, or 
right to view contents that weren’t originally shown. 


side effects: A feature of C expressions in which using an assignment oper- 
ator in an expression affects the value of one of the components used 
in the expression. 


simulator: A development tool that simulates the operation of the ’C3x and 
lets you execute and debug applications programs by using the ’C38x de- 
bugger. 
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single-step: A form of program execution that allows you to see the effects 
of each statement. The program is executed statement by statement; the 
debugger pauses after each statement to update the data-display win- 
dows. 


symbol table: A file that contains the names of all variables and functions 
in your ’C3x program. 


system shell: A utility invoked with the SYSTEM command, which makes 
it possible for the debugger to blank the debugger display and temporari- 
ly exit to the DOS prompt. This allows you to enter DOS commands or 
allows the debugger to display information resulting from a DOS com- 
mand. 


target system: A ’C3x board that works with the emulator; the emulator 
doesn’t contain a’C3x device, so it must use a’C3x target board. Usually, 
the target system is a board that you have designed; you use the emula- 
tor and debugger to help you debug your design. 


VGA: Video Graphics Array. An industry standard for video cards. 


WATCH window: A window that displays the values of selected expres- 
sions, symbols, addresses, and registers. 


window: A defined rectangular area of virtual space on the display. 
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Note: All page numbers preceded by the word EMU refer to the TMS320C3x Emulator Installation 
Guide; page numbers preceded by S/M refer to the TMS320C3x Simulator Getting Started Guide, and 
page numbers preceded by EVM refer to the TMS320C3x EVM Installation Guide. All other references 
refer to this user’s guide. 


? command 7-3, 11-11 ADDR command 6-5, 6-9, 11-12 
display formats 2-24, 7-20, 11-11 effect on DISASSEMBLY window 3-7 
examining register contents 2-16, 7-10 effect on FILE window 3-8 
modifying PC 6-12 finding current PC 6-12 
side effects 7-5 addresses 


absolute addresses 7-7, 8-3 


$$EMU$$ constant 4-14 accessible locations 5-1, 5-2 


$$EVM$$ 4-14 contents of (indirection) 7-8, 7-15 
hexadecimal notation 7-7 
SSSIM$$_ 4-14 I/O address space EMU 4 to 5, 12; EVM 4,5, 10 


simulator 5-13 to 5-19 
in MEMORY window 2-5, 3-12, 7-7 
invalid memory 5-3 
Al nonexistent memory locations 5-2 
pointers in DISP window 2-21 
protected areas 5-3 
symbolic addresses 7-7 


absolute addresses /7-7, 8-3 
undefined areas 5-3 


active window 3-19 to 3-21 


aggregate types 

breakpoints 8-3 "Genin : F-1 
current field 2-6, 3-18 displaying 2-20, 3-16, 7-12 to 7-14 
customizing its appearance 9-4 ALIAS command 2-27, 4-17 to 4-18, 11-12 
default appearance 3-19 supplying parameters 4-17 
definition F-1 aliasing 4-17 to 4-18 
effects on command entry 4-3 ALIAS command 2-27, 4-17 to 4-18 
identifying 2-6, 3-19 definition F-1 
moving 2-9, 3-24 to 3-26 deleting aliases 4-18 
selecting 3-20, 11-46 finding alias definitions 4-18 

function key method 2-6, 3-20, 11-54 limitations 4-18 

mouse method 2-6, 3-20 listing aliases 4-17 

WIN command 2-5, 3-20 redefining an alias 4-18 
sizing 2-7, 3-21 to 3-23 ANSI C 
zooming 2-8, 3-23 to 3-30, 11-47 definition F-1 
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area names (for customizing the display) 
code-display windows 9-5 
COMMAND window 9-4 
common display areas 9-3 
data-display windows 9-6 
menus 9-7 
summary of valid names 9-3 
window borders 9-4 
arithmetic operators 12-2 
arrays 
displaying/modifying contents 7-12 
format in DISP window 2-21, 7-13, 11-19 
member operators 12-2 
arrow keys 
COMMAND window 4-3 
editing 7-4 
moving awindow 2-9, 3-25, 11-54 
moving adjacent windows 4-9 
scrolling 2-10, 3-27, 11-56 
sizing awindow 2-7, 3-23, 11-55 
—as shell option 10-2 
ASM command 2-13, 6-3, 11-13 
menu selection 11-10 
assembler 1-9, 1-10; EMVU3; EVM3; SIM 1-3, 
2-2, 3-2 
assembly language code 
displaying 3-2 to 3-3, 6-4 
modifying 6-5 to 6-6 
assembly mode 2-12, 2-13, 3-3 to 3-30, 6-2 
ASM command 2-13, 6-3, 11-13 
definition F-1 
selection 6-3 
assignment operators 7-5, 12-3 
attributes 9-2 
auto mode 2-12, 2-13, 3-2 to 3-3, 6-2 
Ccommand 2-13, 6-3, 11-15 
definition F-1 
selection 6-3 
autoexec.bat file EWU9 to 12; EVM7 to 10; 
SIM 1-5 to 1-7 
definition F-1 
invoking EMU 10; EVM8; SIM 1-6 
sample EMU 10; EVM8; SIM 1-5 
auxiliary registers 7-10 
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—b debugger option 1-12, 1-13 
effect on window positions 3-25 
effect on window sizes 3-22 
with D_OPTIONS environment variable EMU 12; 
EVM9; SIM1-7 


BA command 8-3, 11-13 
menu selection 11-9 


background 9-3 


batch files 4-12 
autoexec.bat EMU 9 to 12; EVM 7 to 10; 
SIM 1-5 to 1-7 
sample EMU 10; EVM 8 
controlling command execution 4-14 to 4-20 
conditional commands 4-14 to 4-20, 11-4, 
11-23 
looping commands 4-15 to 4-20, 11-4, 11-24 
definition F-1 
displaying 6-9 
displaying text when executing 4-13, 11-4, 
11-21 
echoing messages 4-13, 11-4, 11-21 
emurst EMU 3, 12 
evmrst EVM 3, 10 
execution 11-43 
halting execution 4-12 
init.clr 9-9; EMU3; EVM3 
PC systems SIM 1-3 
Sun systems SIM 3-2 
VAX systems SIM 2-2 
initcmd 5-2,D-1; EMU3; EVM3 
definition F-4 
PC systems SIM 1-3 
Sun systems SIM 3-2 
VAX systems SIM 2-2 
initdb.bat EMU9 to 12; EVM7to 10; SIM 1-5 to 
1-7 
sample EMU 10; EVM 8 
initialization 5-2 to 5-20, D-1 
init.cmd 5-2, D-1; EMU 3; EVM 3 
PC systems S/M1-3 
Sun systems S/M 3-2 
VAX systems S/M 2-2 


batch files (continued) 
invoking 
autoexec.bat EMU 10; EVM 8; SIM 1-6 
initdb.bat EMU 10; EVM 8; SIM 1-6 
memory maps 5-12 
mono.clr EMU 3; EVM3 
PC systems SIM 1-3 
Sun systems SIM 3-2 
VAX systems SIM 2-2 
TAKE command 4-12, 5-12, 11-43 
-bb debugger option. See -b debugger option 
BD command 8-4, 11-13 
menu selection 11-9 
benchmarking 6-19 
constraints 6-19 
definition F-2 
bitwise operators 12-3 
BL command 8-5, 11-13 
menu selection 11-9 
blanks 9-3 
BORDER command 9-8, 11-14 
menu selection 11-10 
borders 
colors 9-4 
styles 9-8 
BRcommand 2-16, 8-4, 11-14 
menu selection 11-9 
breakpoints, software 8-1 
active window 2-6 
adding 8-2, 11-13 
command method 8-3 
function key method 8-3, 11-55 
mouse method 8-3 
benchmarking with RUNB_ 6-19 
clearing 2-16, 8-4, 11-13, 11-14 
command method 8-4 
function key method 8-4, 11-55 
mouse method 8-4 
commands 11-2, 11-5 
BA command 8-3, 11-13 
BD command 8-4, 11-13 
BL command 8-5, 11-13 
BRcommand 2-16, 8-4, 11-14 
cache interaction B-2 
menu selections 11-9 
constraints B-4 to B-6 
delayed branches B-4 
repeat block B-4 
repeat single B-4 
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breakpoints, software (continued) 
definition F-2 
highlighting 8-2 
listing set breakpoints 8-5, 11-13 
restrictions 8-2 
setting 2-15 to 2-28, 8-2 
command method 8-3 
function key method 8-3, 11-55 
mouse method 8-3 
buffer delays for emulator connections A-4 


C command 2-13, 6-3, 11-15 
menu selection 6-3, 11-10 
C expressions 7-5, 12-1 to 12-6 
See also expressions 
C language 
definition F-2 
C source 
displaying 2-11, 3-2 to 3-3, 6-4, 11-22 
managing memory data 7-8 
c3xhll directory EMU9, 11; EVM7,9 
cache 
See also memory cache 
control 
memory commands B-3 
interaction 
breakpoint commands B-2 
P-flags B-2 
CALLS command 3-9, 3-10, 6-9, 11-15 
effect on debugging modes_ 3-4 
CALLS window 2-11, 3-5, 3-9 to 3-30, 6-2, 6-9 
closing 3-10, 3-29, 11-54 
definition F-2 
opening 3-10, 11-15 
casting 2-23, 12-4 
definition F-2 
CHDIR (CD) command 2-20, 4-20, 6-11, 11-15 
children 
See also DISP window, children 
definition F-2 
cl30 shell 1-11 
clearing the display area 2-20, 4-5, 11-16 
“click and type” editing 2-25, 3-28, 7-4 to 7-5 
clicking 
definition F-2 
CLK pseudoregister 6-19 
definition F-2 
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closing 
awindow 3-29 
CALLS window 3-10, 11-54 
debugger 1-15, 2-27, 11-34 
dialog box 4-12 
DISP window 2-22, 7-14, 11-54 
log files 4-6, 11-20 
MEMORY window 3-14 
WATCH window 7-16, 11-47 
CLS command 2-20, 4-5, 11-16 
CNEXT command 6-15, 11-16 


code 
debugging 1-16 
code-display windows 3-5, 6-2 
CALLS window 2-11, 3-5, 3-9 to 3-30, 6-2, 6-9 
definition F-2 
DISASSEMBLY window 2-5, 3-5, 3-7, 6-2, 6-4 
effect of debugging modes_ 6-2 
FILE window 2-11, 3-5, 3-8, 6-2, 6-4, 6-8 
code-execution (run) commands. See run com- 
mands 


COFF 
definition F-2 
loading 5-3 


COLOR command 9-2, 11-16 to 11-17 
color.clr file 9-9 


colors 9-2 to 9-7 
areanames 9-3 to 9-7 


comma operator 12-4 


command history 4-5 
function key summary 11-52 
commandline 3-6, 4-2 
changing the prompt 9-11, 11-33 
cursor 3-18 
customizing its appearance 9-4, 9-11 
definition F-2 
editing 4-3 
function key summary 11-52 
COMMAND window _ 3-5, 3-6, 4-2 
colors 9-4 
commandline 2-4, 3-6, 4-2 
editing keys 11-52 
customizing 9-4 
definition F-2 
display area 2-4, 3-6, 4-2 
clearing 11-16 
recording information from the display area 4-6 
to 4-8, 11-4, 11-20 
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commands 
alphabetical summary 11-11 to 11-47 
batch files 4-12 
controlling command execution 
conditionalcommands 4-14 to 4-20, 11-4, 11-23 
looping commands 4-15 to 4-20, 11-4, 11-24 
breakpoint commands 8-1, 11-2, 11-5 
See also breakpoints (software), commands 
code-execution (run) commands 6-12 
See also run commands 
commandline 4-2 
command strings 4-17 to 4-18 
customizing 4-17 to 4-18 
data-management commands 7-2 to 7-20, 11-2, 
11-3 
See also data-management commands 
entering and using 4-1 to 4-20 
file-display commands 6-4 to 6-9, 11-2, 11-5 
See also file/load commands 
load commands’ 6-10, 11-2, 11-5 
See also file/load commands 
memory commands _ 5-7 to 5-19 
See also memory, commands 
memory-map commands 11-2, 11-6 
See also memory, mapping 
menu selections 4-7 
mode commands 6-2 to 6-3, 11-2, 11-3 
See also debugging modes, commands 
notation v to vii 
profiling commands 11-2, 11-8 
See also profiling commands 
runcommands 11-2, 11-7 
See also run commands 
screen-customization commands 9-1 to 9-12, 
11-2, 11-5 
See also screen-customization commands 
system commands 4-19 to 4-20, 11-2, 11-4 
See also system commands 
window commands 11-2, 11-3 
See also window commands 
compiler 1-8, 1-10; EMU3; EVM3; SIM 1-3, 2-2, 
3-2 
key characteristics 1-8 
conditionalcommands 4-14 to 4-20, 11-23 


connector 
12-pin header A-2 
mechanical dimensions A-6 to A-7 
target system to emulator A-1 to A-8; EMU7 


CPU clock cycles 
simulating interrupts 5-16 to 5-19 


CPU window 3-5, 3-15, 7-2, 7-10 to 7-11 
colors 9-6 
customizing 9-6 
definition F-3 
editing registers 7-4 
CSTEP command 2-17, 6-15, 11-17 


current directory 
changing 4-20, 6-11, 11-15 
current field 
cursor 3-18 
editing 7-4to 7-5 
current PC 2-4, 3-7 
finding 6-12 
selecting 6-12 
cursors 3-18 
command-line cursor 3-18 
definition F-2 
current-field cursor 3-18 
definition F-3 
definition F-3 
mouse cursor 3-18 
definition F-5 
customizing the display 9-1 to 9-12 
changing the prompt 9-11 
colors 9-2 to 9-7 
init.clr file 9-11, 11-37; EMU3; EVM3 
PC systems SIM 1-3 
Sun systems SIM 3-2 
VAX systems SIM 2-2 
loading acustom display 9-10 
mono.clr file EMU 3; EVM3 
PC systems SIM 1-3 
Sun systems SIM 3-2 
VAX systems SIM 2-2 
saving a custom display 9-9 
window border styles 9-8 


D_DIR environment variable 4-12, 9-10, 11-37; 
EMU 11; EVM9; SIM 1-7 
definition F-3 
effects on debugger invocation D-1 
D_OPTIONS environment variable EMU 12; 
EVM9; SIM 1-7 
definition F-3 
effects on debugger invocation D-1 
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D_SRC environment variable 6-11; EMU 11; 
EVM9; SIM 1-7 
definition F-3 
effects on debugger invocation D-1 
DASM command 6-5, 11-18 
effect on debugging modes_ 3-4 
effect on DISASSEMBLY window 3-7 
finding current PC 6-12 


data 
in MEMORY window 3-12 


dataformats 7-18 
datatypes 7-19 


data memory 
adding to memory map 5-7 
deleting from memory map 5-11 
filling 7-9 
saving 7-9 
datatypes 7-19 
See also display formats 
data-display windows 2-20, 3-5, 7-2 
colors 9-6 
CPU window — 3-5, 3-15, 7-2, 7-10 
definition F-3 
DISP window 2-20, 3-5, 3-16, 7-2, 7-12 to 7-14 
MEMORY window 2-5, 3-5, 3-12 to 3-14, 7-2, 
7-6 to 7-9 
WATCH window 2-16, 3-5, 3-17, 7-2, 7-14 to 
7-16 
data-management commands 7-2, 11-2, 11-3 
2?command 2-16, 6-12, 7-3, 11-11 
controlling data format 2-23 to 2-28 
data-format control 7-18 to 7-20 
DISP command 2-20, 7-12, 11-18 
EVAL command 6-12, 7-3, 11-21 
FILL command 7-9, 11-22 
MEM command 2-5, 3-13, 3-14, 7-7, 11-27 
MS command 7-9, 11-30 
SETF command 2-23, 7-18 to 7-20, 11-38 
side effects 7-5 
WA command 2-16, 4-11 to 4-13, 7-15, 11-45 
WD command 2-18, 7-16, 11-46 
WHATIS command 2-19, 7-2, 11-46 
WRcommand 2-19 to 2-28, 7-16, 11-47 
debugger 
definition F-3 
description 1-2 to 1-4 
display 2-4 
basic 1-2 
profiling-environment 1-5 
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debugger (continued) 


environment setup EMU 9 to 12; EVM7 to 10; 
SIM 1-5 to 1-7 
exiting 1-15 
installation EMU 1 to 15; EVM7 
error messages EMU 14; EVM 12 
EVM EVM 1 to 12 
simulator 
PC systems S/M 1-1 to 1-9 
Sun systems S/M 3-1 to 3-4 
VAX systems S/M 2-1 to 2-5 
verifying EMU 13; EVM 11; SIM 1-8, 2-4, 3-3 
to 3-4 
invocation 1-12 to 1-15, 2-3 
options 1-12to 1-15 
task ordering D-1 
key features 1-3 to 1-4 
messages E-1 to E-20 
using with MS-Windows EMU 9, 15; EVM7, 12; 
SIM 1-4, 1-9 
exiting 1-15 


debugging modes 2-12 to 2-28, 3-2 to 3-4, 6-2 to 


6-3 
assembly mode 2-12, 3-3 to 3-30, 6-2 
auto mode 2-12, 3-2 to 3-3, 6-2 
commands 
ASM command 2-13, 11-13 
Ccommand 2-13, 6-3, 11-15 
menu selections 2-13, 6-3, 11-8 
MIX command 2-13, 6-3, 11-28 
default mode 3-2, 6-2 
menu selections 2-13, 6-3 
mixed mode 2-12, 3-4 
restrictions 3-4 
selection 2-12 
command method 6-3 
commands 2-13 
function key method 6-3, 11-53 
mouse method 6-3 


decrement operator 12-3 


default 


data formats 7-18 

debugging mode 3-2, 6-2 

display 2-4, 3-2, 6-2, 9-11 

I/O address space EMU 4 to 5; EVM 4,5 
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default (continued) 
memory map 2-26, 5-4; EMU3; EVM3 
emulator 5-5 
EVM 5-6 
PC systems SIM 1-3 
simulator 5-4 
Sun systems SIM 3-2 
VAX systems SIM 2-2 
screen configuration file 9-9; EVM3 
color displays EMU 3; EVM 3; SIM 1-3, 2-2, 
3-2 
monochrome displays 9-9; EMU 3; EVM 3; 
SIM 1-3, 2-2, 3-2 
PC systems SIM 1-3 
Sun systems SIM 3-2 
VAX systems SIM 2-2 
switch settings EMU 4 to 5; EVM 4 
defining areas for profiling 10-5 to 10-12 
disabling areas 10-7 to 10-22 
enabling areas 10-10 to 10-22 
marking areas 10-5 to 10-22 
restrictions 10-12 to 10-22 
unmarking areas 10-11 to 10-22 
dialog boxes 4-11 to 4-12 
entering parameters 4-11 to 4-13 
modifying textin 4-12 
using 4-11 to 4-12 
DIR command 2-20, 4-20, 11-18 
directories 
c3xhll directory EMU9, 11; EVM 7,9 
changing current directory 4-20, 11-15 
for auxiliary filles EMU 11; EVM9; SIM 1-7 
for debugger software EMU 9, 11; EVM7,8 
PC systems SIM 1-4, 1-6 
Sun systems SIM 3-3 
VAX systems SIM 2-3 
identifying additional source directories 11-44; 
EMU 11; EVM9; SIM 1-7 
USE command 11-44 
identifying current directory 6-11 
listing contents of current directory 4-20, 11-18 
relative pathnames 4-20, 11-15 
search algorithm 4-12, 6-11, D-1 
sim3x directory 
PC systems SIM 1-4, 1-7 
Sun systems SIM 3-3 
VAX systems SIM 2-3 


disabling areas 10-7 to 10-22 


disassembly 
definition F-3 


DISASSEMBLY window 2-5, 3-5, 3-7, 6-2, 6-4 
colors 9-5 
customizing 9-5 
definition F-3 
modifying display 11-18 


DISP command 2-20, 3-16, 7-12, 11-18 
display formats 2-23, 2-24, 7-20, 11-19 
effect on debugging modes 3-4 


DISP window 2-20, 3-5, 3-16, 7-2, 7-12 to 7-14 
children 
closing 2-22 
definition F-2 
closing 2-20, 2-22, 3-29 to 3-30, 7-14 
colors 9-6 
customizing 9-6 
definition F-3 
effects of LOAD command 7-14 
effects of SLOAD command 7-14 
identifying arrays, structures, pointers 11-19 
opening 7-12 
opening another DISP window 7-13 
command method 7-13 
function key method 2-22, 7-13, 11-55 
mouse method 2-21 


display area 3-6, 4-2 
clearing 2-20, 4-5, 11-16 
definition F-3 
recording information from 4-6 to 4-8, 11-4, 
11-20 


display formats 2-23 to 2-28, 7-18 to 7-20 
2? command 2-24, 7-20, 11-11 
casting 2-23 
datatypes 7-19 
DISP command 2-23, 2-24, 7-20, 11-19 
enumerated types 3-16 
floating-point values 3-16 
integers 3-16 
MEM command 2-24, 7-20, 11-27 
pointers 3-16 
SETF command 2-23, 7-18 to 7-20, 11-38 
WA command 2-23, 7-20, 11-45 


display requirements EMU 2; EVM2 
PC systems SIM 1-2 
Sun systems S/M 3-2 
VAX systems S/M 2-2 
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displaying 
assembly language code 6-4 
batch files 6-9 
Ccode 6-8 
data in nondefault formats 7-18 to 7-20 
source programs 6-4 to 6-9 
text files 6-9 
text when executing a batch file 4-13, 11-4, 
11-21 


DLOG command 4-6 to 4-8, 11-4, 11-20 
ending recording session 4-6 
starting recording session 4-6 


DOS 
See also MS-DOS 
display requirements EMU 2 
error messages 
installation EMU 14 
graphics card requirements EMU 2 
hardware requirements EMU 2 
host system EMU 2 
memory requirements EMU 2 
mouse requirements EMU 2 
operating system EMU3 
power requirements EMU 2 
setting up debugger environment EMU 9 to 12; 
EVM 7 to 10; SIM 1-5 to 1-7 
software requirements EMU 3 
target system EMU2 
using MS-Windows EMU 9, 15 
dragging 
definition F-3 


Ecommand 11-21 
See also EVAL command 


ECHO command 4-13, 11-4, 11-21 

“edit” key (F9) 3-28, 7-4, 7-5, 11-55 
See also F9 key 

editing 
“click and type” method 2-25, 3-28, 7-4 to 7-5 
commandline 4-3, 11-52 
data values 7-4 to 7-5, 11-55 
dialog boxes 4-11 to 4-12 
disassembly 6-5 to 6-9, 11-31 to 11-47 
FILE, DISASSEMBLY, CALLS 3-28 
function key method 2-26, 7-4, 11-55 
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editing (continued) 
MEMORY, CPU, DISP, WATCH 3-28 
mouse method 7-4 
overwrite method 7-4 to 7-5 
window contents 3-28 


EGA 
definition F-4 

EISA 
definition F-4 

ELSE command 4-14 to 4-20, 11-4, 11-23 
See also |F/ELSE/ENDIF commands 


$$EMU$$ constant 4-14 


emu3x command 1-12, 2-3, 6-10 
options 1-12 to 1-15 
-b 1-12, 1-13 
D_OPTIONS environment variable D-1; 
EMU 12 
-i 1-12, 1-13, 6-11 
—p 1-12, 1-14 
-profile 1-12, 1-14, 10-3 
-s 1-12, 1-14, 6-10 
—t 1-12, 1-15 
—v 1-12, 1-15 
-x 1-12, 1-15 
verifying the installation EMU 13 


emulator 
additional tools EMU3 
bufferdelays A-4 
connection to target system EMU 8 
connector 
mechanical dimensions A-6 to A-7 
constraints B-1 to B-5 
custom switch settings EMU 5 
debugger environment EMU9 to 12 
debugger installation EMU 1 to 15 
error messages EMU 14 
verifying EMU 13 
definition F-4 
$$EMU$$ constant 4-14 
host system EMU 2 
I/O address space EMU 4 to 5, 12 
installation 
board EMU 4 to 7, 8 
debugger software EMU 9 
error messages EMU 14 
into PC EMU 6 to 7 
preparation EMU 4 to 5 
verifying EMU 13 
invoking the debugger 1-12, 2-3 
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emulator (continued) 
memory 
default map EMU 3 
operating system EMU3 
requirements 
display EMU 2 
graphics card EMU 2 
hardware EMU 2 
memory EMU 2 
mouse EMU 2 
power EMU 2 
software EMU 3 
resetting EMU3, 12 
constraints B-5 
screen 
configuration files EMU 3 
signal buffering A-3 
switch settings EMU 4 to 5, 12 
target cable EMU7 
target system EMU 2 
troubleshooting C-1 to C-6 


emurst file EMU3, 12 
definition F-4 


enabling areas 10-10 to 10-22 


end key 
scrolling 3-27, 11-56 


ENDIF command 4-14 to 4-20, 11-4, 11-23 
See also IF/ELSE/ENDIF commands 


ENDLOOP command 4-15 to 4-20, 11-4, 11-24 
See also LOOP/ENDLOOP commands 


entering commands 
from menu selections 4-7 to 4-10 
onthe commandline 4-2 to 4-6 


entry point 6-12 


enumerated types 
display format 3-16 


environment variables 


D_DIR 4-12, 9-10; EMU 11; EVM9; SIM 1-7 


D_OPTIONS 1-12, D-1; EMU12; EVM9; 
SIM 1-7 

D SRC 6-11; EMU 11; EVM9; SIM 1-7 

definition F-4 


for debugger options 1-12; EMU12; EVM9; 


SIM 1-7 


identifying auxiliary directories EMU 11; EVM 9; 


SIM 1-7 


identifying source directories EMU 11; EVM 9; 


SIM 1-7 


error messages 
beeping 11-40, E-2 
installation EMU 14; EVM 12 
EVAL command 7-3, 11-21 
modifying PC 6-12 
side effects 7-5 


EVM 


additional tools EVM3 
custom switch settings EVM5 


debugger environment EVM 7 to 10 
debugger installation EVM 1 to 12 


error messages EVM 12 
verifying EVM 11 
definition F-4 
$$EVM$$ constant 4-14 
host system EVM2 
I/O address space EVM 4, 5, 10 
installation 
board EVM 4to6 
debugger software EVM 7 
error messages EVM 12 
into PC EVM6 
preparation EVM 4 
verifying EVM 11 
invoking the debugger 1-12, 2-3 
operating system EVM3 
requirements 
display EVM 2 
graphics card EVM 2 
hardware EVM 2 
memory EVM 2 
mouse EVM 2 
power EVM 2 
software EVM 3 
resetting EVM 3, 10 
switch settings EVM 4, 5, 10 


$$EVM$$ constant 4-14 


evm30 command 1-12, 2-3, 6-10 
options 1-12 to 1-15 


—b 


D_OPTIONS environment variable 


= 
=p 


1-12, 1-13 


EVM9 
1-12, 1-13, 6-11 
1-12, 1-14 


-profile 1-12, 1-14 


—s 


1-12, 1-14, 6-10 
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evm30 command, options (continued) 


—t 1-12, 1-15 
-—v 1-12, 1-15 
—-x 1-12, 1-15 
verifying the installation EVM 11 


evmrst file EVM3, 10 


definition F-4 


executing code 2-11, 6-12 to 6-17 


See also run commands 

benchmarking 6-13 

conditionally 2-18, 6-17 

function key method 11-54 

halting execution 2-14, 6-18 

program entry point 2-15 to 2-28, 6-12 to 6-17 

single-stepping 2-17, 11-16, 11-17, 11-30, 11-41 

while disconnected from the target system 6-16, 
11-36 


executing commands 4-3 
exiting the debugger 1-15, 2-27, 11-34 
expressions 12-1 to 12-6 


addresses 7-7 
evaluation 
with ?command 7-3, 11-11 
with DISP command 11-18 
with EVAL command 7-3, 11-21 
with LOOP command 4-16, 11-24 
expression analysis 12-4 
operators 12-2 to 12-3 
restrictions 12-4 
side effects 7-5 
void expressions 12-4 


extended-precision registers (RO-R7) 12-4 
extensions 


filename 1-11 


external interrupts 


connecting input file 5-18, 11-32 
disconnecting pins 5-19, 11-32 
listing pins 5-19, 11-32 
PINC command 5-18, 11-32 
PIND command 5-19, 11-32 
PINL command 5-19, 11-32 
programming simulator 5-18 
setting up input files 5-16 
absolute clock cycle 5-16 
relative clock cycle 5-16 
repetition 5-17 
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FO-F7 (floating-point registers) 12-4 
F2key 4-5 

F3 key 6-3, 11-53 

F4key 2-22, 3-14, 3-29, 7-14, 11-54 
F5 key 4-10, 6-13, 11-9 

F6 key 2-6, 3-20 

F8 key 4-10, 6-15, 11-9 


FQ9 key 2-26, 3-7, 3-8, 3-9, 3-10, 3-28, 6-9, 7-5, 


7-13, 8-4 
Fi0 key 4-10, 6-15, 11-9 


FILE command 2-11, 2-14, 6-8, 11-22 
changing the current directory 4-20, 11-15 
effect on debugging modes 3-4 
effect on FILE window 3-8 
menu selection 11-9 

FILE window 2-11, 2-14, 3-5, 3-8, 6-2, 6-4, 6-8 
colors 9-5 
customizing 9-5 
definition F-4 

file/load commands 11-2, 11-5 
ADDR command _ 6-5, 6-9, 6-12, 11-12 
CALLS command 3-9, 3-10, 6-9, 11-15 
DASM command _ 6-5, 6-12, 11-18 
FILE command 2-11, 2-14, 6-8, 11-22 
FUNC command 2-14, 6-8, 11-22 
LOAD command 2-4, 6-10, 11-24 
menu selections 11-9 
PATCH command 6-5, 11-31 
RELOAD command 6-10, 11-34 
SLOAD command 6-10, 11-40 

files 
connecting to I/O ports 5-13 to 5-20, 11-26 
disconnecting from I/O ports 5-15, 11-28 
log files 4-6 to 4-8, 11-20 
saving memory to afile 7-9 

FILL command 7-9, 11-22 
menu selection 11-10 

floating-point 
display format 2-23, 3-16 
Operations 12-4 
registers (FO-F7) 12-4 

FUNC command 2-14, 6-8, 11-22 
effect on debugging modes 3-4 
effect on FILE window 3-8 
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function calls 

displaying functions 11-22 
keyboard method 3-10 
mouse method 3-10 

executing function only 11-35 

in expressions 12-4 

stepping over 11-16, 11-30 

tracking in CALLS window 3-9 to 3-30, 6-9, 
11-15 


-g shell option 1-10, 1-11, 10-2 
GO command 2-11, 6-13, 11-23 


graphics card requirements EMU 2; EVM 2; 
SIM 1-2 


grouping/reference operators 12-2 


HALT command 6-16, 11-23 
halting 
batch file execution 4-12 
debugger 1-15, 2-27, 11-34 
program execution 1-15, 2-14, 6-12, 6-18 
function key method 6-18, 11-53 
mouse method 6-18 
target system 11-23 
hardware checklist EMU 2; EVM2 
PC systems SIM 1-2 
Sun systems S/M 3-2 
VAX systems SIM 2-2 
header 
12-pin A-2 
mechanical dimensions A-6 to A-7 
hex conversion utility 1-9 
hexadecimal notation 
addresses 7-7 
dataformats 7-18 
history 
ofcommands 4-5 
home key 
scrolling 3-27, 11-55 
host system EMU 2; EVM2 
PC systems SIM 1-2 
Sun systems S/M 3-2 
VAX systems S/M 2-2 


-i debugger option 1-12, 1-13, 6-11 
with D_OPTIONS environment variable EMU 12; 
EVM 9; SIM 1-7 
I/O address space EMU 4 to 5,12; EVM 4, 5, 10 


1/O memory 
simulating 5-13 to 5-19, 11-26, 11-28 
configuring memory 5-15 
connecting port 5-13 to 5-20 
disconnecting port 5-15 
I/O switch settings 
default settings EMU 4 to 5; EVM4,5 
definition F-4 
icons 
method identification v 
mouse actions v 
IF/ELSE/ENDIF commands 4-14 to 4-20, 11-4, 
11-23 
conditions 4-16, 11-24 
creating initialization batch file 4-15 
predefined constants 4-14 
increment operator 12-3 
index numbers 
for data in WATCH window 3-17, 7-16 
indirection operator (*) 7-8, 7-15 
init.clr file 9-9, 9-10, 11-37, D-1; EMU3; EVM3 
PC systems SIM 1-3 
Sun systems S/M 3-2 
VAX systems SIM 2-2 
init.cmd file 5-2, D-1; EMU3; EVM3 
definition F-4 
PC systems SIM 1-3 
Sun systems S/M 3-2 
VAX systems S/M 2-2 
initdb.bat file EWVU9 to 12; EVM7to 10; SIM1-5to 
1-7 
definition F-4 
invoking EMU 10; EVM8; SIM 1-6 
sample EMU 10; EVM8; SIM1-5 
initialization batch files 5-2 to 5-20, D-1 
creating using IF/ELSE/ENDIF 4-15 
creating using LOOP/ENDLOOP_ 4-15 to 4-20 
initcmd 5-2, D-1; EMU3; EVM3 
PC systems SIM 1-3 
Sun systems SIM 3-2 
VAX systems SIM 2-2 
naming an alternate file 1-12, 1-15 
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installation 
board EVM 4 to6 
debugger software EMU9; EVM7 
PC systems SIM 1-4 
Sun systems SIM 3-3 
VAX systems SIM 2-3 
emulator EMU 4 to 7 
error messages EMU 14; EVM 12 
verifying EMU 13; EVM 11 
PC systems SIM 1-8 
Sun systems SIM 3-3 to 3-4 
VAX systems SIM 2-4 


integer 
display format 3-16 
SETF command 7-18 


interrupt pins 5-16 to 5-19 


interrupts 
See also external interrupts 
receiving 11-26 
transmitting 11-26 


invalid memory addresses 5-3 


invoking 
autoexec.bat file EMU10; EVM 8; SIM 1-6 
custom displays 9-11 
debugger 1-12 to 1-15, 2-3 
initdb.bat file EMU 10; EVM8; SIM 1-6 
shell program 1-11 


ISA 
definition F-4 


key sequences 
displaying functions 11-55 
displaying previous commands (command histo- 
ry) 11-52 
editing 
command line 4-3, 11-52 
data values 3-28, 11-55 
halting actions 11-53 
menu selections 11-53 
moving a window 3-25, 11-54 
opening additional DISP windows 11-55 
restrictions 
Sun systems SIM 3-4 
VAX systems SIM 2-5 
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key sequences (continued) logical operators 12-2 
running code 11-54 conditional execution 6-17 
scrolling 3-27, 11-55 LOOP/ENDLOOP commands 4-15 to 4-20, 11-4, 
selecting the active window 3-20, 11-54 11-24 
setting/clearing breakpoints 11-55 conditions 4-16, 11-25 
single stepping 6-15 looping commands 4-15 to 4-20, 11-24 
sizing a window 3-23, 11-54 
switching debugging modes_ 11-53 MI] 
keyboard mapping S/M 2-5 


MA command 2-26, 5-4, 5-7, 5-11, 11-25 to 11-26 


menu selection 11-10 
managing data 7-1 to 7-20 
labels, basic commands 7-2 to 7-3 
for data in WATCH window 2-17, 3-17, 7-15 MAP command 5-9, 11-26 
limits menu selection 11-10 
breakpoints 8-2 mapping 
file size 6-9 modifying 5-11 
open DISP windows 3-16 simulating 
paths 6-11 memory cache. See memory, mapping 
window positions 3-25, 11-29 marking areas 10-5 to 10-22 
window sizes 3-22, 11-39 MC command 5-13 to 5-20, 11-26 
linker 1-9, 1-10; EMU3; EVM3; SIM 1-3, 2-2, 3-2 menu selection 11-10 
command files MD command 2-26, 5-11, 11-27 
MEMORY definition 5-2 to 5-20 menu selection 11-10 
LOAD command 2-4, 6-10, 11-24 MEM command 2-5, 3-12, 3-13, 3-14, 7-7, 11-27 
effect on DISP window 7-12 display formats 2-24, 7-20, 11-27 
effect on WATCH window 7-12 effect on debugging modes _ 3-4 
load/file commands 11-2, 11-5 MEM1 command 3-12 
ADDR command _ 6-5, 6-9, 6-12, 11-12 See also MEM command 
CALLS command 3-9, 3-10, 6-9, 11-15 MEM2 command 3-12 
DASM command. 6-5, 6-12, 11-18 See also MEM command 
FILE command 2-11, 2-14, 6-8, 11-22 MEM3 command 3-12 
FUNC command 2-14, 6-8, 11-22 See also MEM command 
LOAD command 2-4, 6-10, 11-24 memory 
menu selections 11-9 batch file search order 5-2, D-1 


PATCH command. 6-5, 11-31 
RELOAD command 6-10, 11-34 
SLOAD command 6-10, 11-40 


cache. See memory, mapping 
commands 11-2, 11-6 
cache control B-3 


loading FILL command 7-9, 11-22 
batch files 4-12 MA command 11-25 
COFF files MAP command 11-26 

restrictions 5-3 MC 5-13 to 5-20 
custom displays 9-10 MD command 11-27 
object code 2-3, 6-10 menu selections 11-10 
after invoking the debugger 6-10 MI 5-15, 11-28 
symbol table only 6-10, 11-40 ML command 11-28 
while invoking the debugger 1-12, 6-10 MR command 11-30 
without symbol table 6-10, 11-34 MS command 7-9, 11-30 
log files 4-6 to 4-8, 11-20 data formats 7-18 


Index-12 


memory (continued) 
datamemory 2-26 
defaultmap 2-26, 5-4; EMU3; EVM3 
emulator 5-5 
EVM 5-6 
PC systems SIM 1-3 
simulator 5-4 
Sun systems SIM 3-2 
VAX systems SIM 2-2 
displaying in different numeric format 2-23 
filling 7-9, 11-22, 11-30 
invalid addresses 5-3 
map 
adding ranges 5-7, 11-25 
connecting an input port to input file 5-14 
defining 5-2 to 5-20 
in a batch file 5-2 
interactively 5-2 
definition F-4 
deleting ranges 11-27 
modifying 5-2 to 5-20 
potential problems 5-3 
reading multiple maps 5-12 
resetting 11-30 
returning to default 5-12 
mapping 2-26, 2-27, 5-1 to 5-19; EVM3 
commands 
MA command 2-26, 5-4, 5-7, 5-11 
MAP command 5-9 
MD command 2-26, 5-11 
menu selections 11-10 
ML command 2-26, 5-10 
MR command 5-11 
deleting ranges 5-11 
disabling 5-9 
init.cmd file EMU 3; EVM 3 
PC systems S/M 1-3 
Sun systems S/M3-2 
VAX systems S/M 2-2 
listing current map 5-10 
multiple maps 5-12 
PC systems SIM 1-3 
resetting 5-11 
simulating 
VO memory 11-28 
VO ports 5-13 to 5-19, 11-28 
serial ports 5-13 
simulating /O ports 11-26 
Sun systems SIM 3-2 
VAX systems SIM 2-2 
nonexistent locations 5-2 
program memory 2-26 
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memory (continued) 

protected areas 5-3 

requirements EMU2; EVM 2; SIM 1-2 

saving 7-9 

simulating 
VYOmemory 11-26, 11-28 
VO ports 5-13 to 5-19, 11-28 
ports, MC command 11-26 
serial ports 5-13 

undefined areas 5-3 

valid types 5-7 


MEMORY window 2-5, 3-5, 3-12 to 3-14, 7-2, 7-6 


to 7-9, 11-27 
additional MEMORY windows 3-13 to 3-14 
address columns 3-12 
closing 3-14 
colors 9-6 
customizing 9-6 
data columns 3-12 
definition F-5 
displaying 
different memory range 3-14 
memory contents 7-6 to 7-8 
modifying display 11-27 
opening additional windows 3-13, 3-14 
memory-map commands 
cache control B-3 
MA command 7-9 
MC command 5-13 to 5-17 
Ml command 5-15 
MEMORY 1 window 3-13 to 3-14 
closing 3-14 
opening 3-13 
MEMORY2 window 3-13 to 3-14 
closing 3-14 
opening 3-13 
MEMORY3 window 3-13 to 3-14 
See also MEMORY window 
closing 3-14 
opening 3-13 
memory-map commands 11-2, 11-6 
FlLL command 11-22 
MA command 11-25 to 11-26 
MAP command 11-26 
MD command 11-27 
menu selections 11-10 
Ml command 11-28 
ML command 11-28 
MR command 11-30 
MS command 11-30 
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menubar 2-4, 4-7 
customizing its appearance 9-7 
definition F-5 
items without menus 4-10 
using menus 4-7 to 4-10 
menu selections 4-7, 11-8 to 11-10 
colors 9-7 
customizing their appearance 9-7 
definition (pulldown menu) F-5 
entering parameter values 4-11 
escaping 4-9 
function key methods 4-9 
listof menus 4-7 
mouse methods 4-8 to 4-9 
moving to another menu 4-9 
profiling 4-8, 10-4 
usage 4-8 to 4-9 
messages E-1 to E-20 
installation errors EMU 14; EVM 12 
Ml command 5-15, 11-28 
menu selection 11-10 
MIX command 2-13, 6-3, 11-28 
menu selection 6-3, 11-10 
mixed mode 2-12, 2-13, 3-4 
definition F-5 
MIX command 2-13, 6-3, 11-28 
selection 6-3 
ML command 2-26, 5-10, 11-28 
menu selection 11-10 
—mm debugger option 1-12 
modes 
assembly mode 2-12, 3-3 to 3-30 
auto mode 2-12 
commands 11-2 
ASM command 2-13, 6-3, 11-13 
Ccommand 2-13, 6-3, 11-15 
menu selections 11-10 
MIX command 2-13, 6-3, 11-28 
during debugger invocation D-1 
menu selections 2-12, 2-13 
mixed mode 2-12, 3-4 
selection 2-12 
commands 2-13, 6-3 
function key method 6-3, 11-53 
mouse method 6-3 
modifying 
assembly language code_ 6-5 to 6-6 
colors 9-2 to 9-7 
commandline 4-3 
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modifying (continued) 
command-line prompt 9-11 
current directory 4-20, 11-15 
datavalues 7-4 to 7-5 
memory map 5-2 to 5-20 
window borders 9-8 
mono.clr file EVU3; EVM3 
PC systems SIM 1-3 
Sun systems S/M 3-2 
VAX systems S/M 2-2 
monochrome monitors 9-9 
mouse 
cursor 3-18 
icon identification v 
requirements EMU 2; EVM2 
PC systems SIM 1-2 
Sun systems SIM 3-2 
restrictions, VAX systems SIM 2-5 
MOVE command 2-9, 3-24, 11-29 
effect on entering other commands 4-4 
moving awindow 3-24 to 3-26, 11-29 
function key method 2-9, 3-25, 11-54 
mouse method 2-9, 3-24 
MOVE command 2-9, 3-24 
XY screen limits 3-25, 11-29 
MR command 5-11, 11-30 
menu selection 11-10 
MS command 7-9, 11-30 
menu selection 11-10 
MS-DOS 
See also DOS 
entering from the commandline 4-19 
exiting from system shell 11-42 
SYSTEM command. See DOS 
MS-Windows 
exiting the debugger 1-15 
using with the debugger EMU 9, 15; EVM7, 12; 
SIM 1-4, 1-9 
—mv debugger option 1-12, 1-14 
with D-OPTIONS environment variable S/M 1-7 


natural format 2-23, 12-5 

NEXT command 2-17, 6-15, 11-30 
from the menubar 4-10 
function key entry 4-10, 11-54 

nonexistent memory locations 5-2 

notational conventions v 


object files 
creating 6-10 
loading 1-12, 11-24 
after invoking the debugger 6-10 
symbol table only 1-12, 1-14, 11-40 
while invoking the debugger 1-12, 2-3, 6-10 
without symbol table 6-10, 11-34 
operating system EMU3; EVM3 
PC systems SIM 1-3 
Sun systems S/M 3-2 
VAX systems S/M 2-2 
operators 12-2 to 12-3 
& operator 7-7 
* operator (indirection) 7-8, 7-15 
side effects 7-5 
optional files EMU3; EVM3 
PC systems SIM 1-3 
Sun systems S/M 3-2 
VAX systems S/M 2-2 


overwrite editing 7-4 to 7-5 


—p debugger option 1-12, 1-14 
with D_OPTIONS environment variable EMU 12, 
14; EVM9 
page-up/page-down keys 
scrolling 3-27, 11-55 
parameters 
cl30 shell 1-11 
emu38x command 1-12 
entering in adialog box 4-11 to 4-13 
evm30 command 1-12 
notation vi 
patch assembly 6-5 
sim3x command 1-12 


PATCH command 6-5, 11-31 
PATH statement EMU 11; EVM 8; SIM 1-6 
PC 6-12 

definition F-5 

finding the current PC 3-7 
PF command 10-15, 11-31 

effect on PROFILE window 3-11 
pincommands 5-18 to 5-19, 11-6 

menu selections 11-10 
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PINC command 5-18, 11-32 
menu selection 11-10 
PIND command 5-19, 11-32 
menu selection 11-10 
PINL command _ 5-19, 11-32 
menu selection 11-10 
pins 
connecting to afile 5-18, 11-32 
disconnecting a file 5-19, 11-32 
listing the pins 5-19, 11-32 
pointers 
displaying/modifying contents 2-21, 7-12 
format in DISP window 2-21, 3-16, 7-13, 11-19 
natural format 12-5 
typecasting 12-5 
pointing 
definition F-5 
portaddress 1-12, 1-14; EMU14; EVM9 
D_OPTIONS EMU 12; EVM9 
definition F-5 
simulator 5-13 to 5-19 
ports 
connecting 5-13 to 5-20 
disconnecting 5-15 
simulating 5-13 to 5-20, 11-26 
configuring memory 5-15 to 5-20 
power requirements, board EMU 2; EVM2 
PQcommand 10-15, 11-33 
effect on PROFILE window 3-11 
PRcommand 10-16, 11-33 
—profile debugger option 1-12, 1-14 
with D_OPTIONS environment variable EMU 12; 
SIM 1-7 
PROFILE window _ 3-5, 3-11, 10-17 to 10-21 
associated code 10-21 
data accuracy 10-19 
displaying areas 10-19 to 10-22 
displaying different data 10-17 to 10-22 
sorting data 10-19 
profiling 10-1 to 10-22 
collecting statistics 
full statistics 10-15, 11-31 
subset of statistics 10-15, 11-33 
commands 11-2, 11-8 
PF command 10-15, 11-31 
PQcommand 10-15, 11-33 
PRcommand 10-16, 11-33 
SA command 10-14, 11-36 
SDcommand_ 10-14, 11-37 
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profiling, commands (continued) 
SL command 10-14, 11-39 
SRcommand 10-14, 11-40 
summary 11-48 to 11-51 
VAA command 10-22, 11-44 
VAC command 10-22, 11-44 
VR command 11-45 
compiling a program for profiling 10-2 
defining areas 10-5 to 10-12 
disabling areas 10-7 to 10-22 
function key method 10-9 
mouse method 10-8 
enabling areas 10-10 to 10-22 
function key method 10-10 
marking areas 10-5 to 10-22 
function key method 10-7 
mouse method 10-6 
restrictions 10-12 to 10-22 
unmarking areas 10-11 to 10-22 
function key method 10-12 
description 1-5 to 1-6 
entering environment 10-3 
key features 1-5 to 1-6 
menu selections 4-8, 10-4 
overview 10-2 
resetting PROFILE window 11-45 
restrictions 
available windows 10-3 
batch files 10-3 
breakpoints 10-3 
commands 10-3 
modes 10-3 
resuming asession 10-16, 11-33 
running asession 10-15 to 10-16 
full 10-15, 11-31 
quick 10-15, 11-33 
saving datatoa file 10-22 
saving statistics 
all views 10-22, 11-44 
current view 10-22, 11-44 
stopping points 10-13 to 10-14 
adding 10-14, 11-36 
command method 10-14 
deleting 10-14, 11-37, 11-40 
listing 10-14, 11-39 
mouse method 10-13 
resetting 10-14, 11-40 
strategy 10-2 
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profiling commands (continued) 
viewing data 10-17 to 10-21 
associated code 10-21 
data accuracy 10-19 
displaying areas 10-19 to 10-22 
displaying different data 10-17 to 10-22 
sorting data 10-19 


program 
debugging 1-16 
entry point 6-12 
resetting 11-34 
execution 
commands 2-11, 11-2, 11-7 
CNEXT command 6-15, 11-16 
conditional parameters 2-18 
CSTEP command 2-17 
GOcommand 2-11, 11-23 
HALT command 11-23 
menu bar selections 11-54 
NEXT command 2-17, 6-15, 11-30 
RESET command 2-4, 11-34 
RESTART command 2-16, 6-12, 11-34 
RETURN command 11-35 
RUN command 2-14, 11-35 
RUNB command 2-16, 6-13, 6-19, 11-35 
RUNF command 11-36 
STEP command 2-17, 6-14, 11-41 
TAKE command 4-12, 5-12, 11-43 
constraints, repeat single B-5 
halting 1-15, 2-14, 6-12, 6-18, 11-53 
preparation for debugging 1-10 


program counter (PC) 7-10 


program memory 
adding to memory map 5-11, 11-25 
adding to the memory map 5-7 
deleting from memory map 5-11, 11-27 
displaying 7-7 
filling 7-9 
saving 7-9 


PROMPT command 9-11, 11-33 
menu selection 11-10 


pseudoregisters 
daddr 7-17 
dins 7-17 
faddr 7-17 
fins 7-17 
raddr 7-17 
rins 7-17 
xaddr 7-17 
xins 7-17 


pulldown menus 
See also menu selections 
definition F-5 
function key methods 11-53 


QUIT command 1-15, 2-27, 11-34 


re-entering commands 4-5, 11-52 
recording COMMAND window displays 4-6 to 4-8, 
11-4, 11-20 
registers 
CLK pseudoregister 6-19 
displaying/modifying 7-10 to 7-11 
extended-precision (RO-R7) 12-4 
floating-point (FO-F7) 12-4 
program counter (PC) 7-10 
referencing by name 12-4 
relational operators 12-2 
conditional execution 6-17 
relative pathnames 4-20, 6-11, 11-15 
RELOAD command 6-10, 11-34 
menu selection 11-9 
repeating commands 4-5, 11-52 
required files EMU3; EVM3 
required tools EMU 3; EVM3 
PC systems SIM 1-3 
Sun systems S/M 3-2 
VAX systems S/M 2-2 
RESET command 2-4, 6-16, 11-34 
menu selection 11-9 
reset vector files EVM3 
resetting EVM3, 10 
emulator, constraints B-5 
emurst file EMU 3, 12 
memory map 11-30 
program entry point 11-34 
target system 2-4, 6-16, 11-34 
RESTART (REST) command 2-16, 6-12, 11-34 
menu selection 11-9 
restrictions 
See also limits; constraints 
breakpoints 8-2 
C expressions 12-4 
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restrictions (continued) 
debugging modes _ 3-4 
PC systems S/M 1-9 
profiling environment 10-3 
Sun systems S/M 3-4 
VAX systems SIM 2-5 
resvet files EVM3 
RETURN (RET) command 6-13, 11-35 
RUN command 2-14, 6-13, 11-35 
from the menu bar 4-10 
function key entry 4-10, 6-13, 11-54 
menu bar selections 4-10 
with conditional expression 2-18 
runcommands 2-11, 11-2, 11-7 
CNEXT command 6-15, 11-16 
conditional parameters 2-18 
constraints, repeat single B-5 
CSTEP command 2-17, 6-15, 11-17 
GOcommand 2-11, 6-13, 11-23 
HALT command 6-16, 11-23 
menu bar selections 4-10, 11-55 
menu selections 11-9 
NEXT command 2-17, 6-15, 11-30 
RESET command 2-4, 6-16, 11-34 
RESTART command 2-16, 6-12, 11-34 
RETURN command 6-13, 11-35 
RUN command 2-14, 6-13, 11-35 
RUNB command 2-16, 6-13, 6-19, 11-35 
RUNF command 6-16, 11-36 
STEP command 2-17, 6-14, 11-41 
TAKE command 4-12, 5-12, 11-43 
RUNB command 2-16, 6-13, 6-19, 11-35 
RUNF command 6-16, 11-36 
running programs 6-12 to 6-17 
conditionally 6-17 
halting execution 6-18 
program entry point 6-12 to 6-17 
while disconnected from the target system 6-16 


—s debugger option 1-12, 1-14, 6-10 
with D_OPTIONS environment variable EMU 12; 
EVM9; SIM 1-7 


SAcommand 10-14, 11-36 
saving custom displays 9-9 


scalar type 
definition F-5 
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SCOLOR command 9-2, 11-36 
menu selection 11-10 


SCONFIG command 9-10, 11-37 
menu selection 11-10 
restrictions 9-10 


screen-customization commands) 11-2, 11-5 
BORDER command 9-8, 11-14 
COLOR command 9-2, 11-16 to 11-17 
menu selections 11-10 
PROMPT command 9-11, 11-33 
SCOLOR command 9-2, 11-36 
SCONFIG command 9-10, 11-37 
SSAVE command 9-9, 11-41 


scrolling 2-10, 3-26 
definition F-5 
function key method 2-10, 3-27, 11-55 
mouse method 2-10, 3-26 to 3-27, 7-8 


SD command 10-14, 11-37 


serial ports 
receive registers 11-26 
serial portO 11-26 
serial port 1 11-26 
simulation 5-13 to 5-16, 11-26 
transmit registers 11-26 


SETF command 2-23, 7-18 to 7-20, 11-38 
shell program 1-11 


side effects 7-5, 12-3 
definition F-5 
valid operators 7-5 


signal buffering for emulator connections A-3 
$$SIM$$ constant 4-14 


sim3x command 1-12, 2-3, 6-10 
options 1-12to 1-15 

-—b 1-12, 1-13 

D_OPTIONS environment variable D-1; 
SIM 1-7 

-i 1-12, 1-13, 6-11 

—mm_ 1-12 

—mv_ 1-12, 1-14 

-profile 1-12, 1-14, 10-3 

-s 1-12, 1-14, 6-10 

—t 1-12, 1-15 

—v 1-12, 1-15 

-x 1-12, 1-15 


verifying the installation S/M 1-8, 2-4, 3-3 to 3-4 
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sim3x directory 
PC systems S/M 1-4, 1-7 
Sun systems S/M 3-3 
VAX systems S/M 2-3 


simulating interrupts 
See also external interrupts 
PINC command 11-32 
PIND command 11-32 
PINL command 11-32 


simulator 
definition F-5 
/O memory 5-13 to 5-19, 11-26, 11-28 
configuring memory 5-15 to 5-20 
connecting port 5-13 to 5-20 
invoking the debugger 1-12, 2-3 
PC systems 
additional tools SIM 1-3 
debugger environment SIM 1-5 to 1-7 
debugger installation SIM 1-1 to 1-9 
verifying SIM 1-8 
host system SIM 1-2 
installation 
software S/M 1-4 
verifying SIM 1-8 
operating system SIM 1-3 
requirements 
display SIM 1-2 
graphics card SIM 1-2 
hardware SIM 1-2 
memory S/M 1-2 
mouse S/M 1-2 
software S/M 1-3 
restrictions SIM 1-9 
restrictions 
color displays 
Sun systems S/M 3-4 
VAX systems S/M 2-5 
keyboard mapping 
Sun systems S/M 3-4 
VAX systems S/M 2-5 
memory map size, PC systems SIM 1-9 
mouse use, VAX systems SIM 2-5 
PC systems SIM 1-9 
Sun systems SIM 3-4 
VAX systems SIM 2-5 
serial ports 5-13 
$$SIM$$ constant 4-14 
simulating 
VYOmemory 11-28 
VO space 5-13 to 5-19, 11-28 
serial ports 5-13 


simulator (continued) 
Sun systems 
additional tools SIM 3-2 
debugger installation SIM 3-1 to 3-4 
verifying SIM 3-3 to 3-4 
host system SIM 3-2 
installation 
software S/M 3-3 
verifying SIM 3-3 to 3-4 
operating system SIM 3-2 
requirements 
display SIM 3-2 
hardware SIM 3-2 
mouse SIM 3-2 
software SIM 3-2 
restrictions SIM 3-4 
VAX systems 
additional tools SIM 2-2 
debugger installation SIM 2-1 to 2-5 
verifying SIM 2-4 
host system SIM 2-2 
installation 
software S/M2-3 
verifying SIM 2-4 
operating system SIM 2-2 
requirements 
display SIM 2-2 
hardware SIM 2-2 
software SIM 2-2 
restrictions SIM 2-5 
single-step 
commands 
CNEXT command 6-15, 11-16 
CSTEP command 2-17, 6-15, 11-17 
menu bar selections 4-10 
NEXT command 2-17, 6-15, 11-30 
STEP command 2-17, 6-14, 11-41 
definition F-6 
execution 6-14 
assembly language code 6-14, 11-41 
Ccode 6-15, 11-17 
function key method 6-15, 11-54 
mouse methods 6-15 
over function calls 6-15, 11-16, 11-30 
SIZE command 2-7, 3-22 to 3-24, 11-39 
effect on entering other commands 4-4 
size of operator 12-4 
sizes 
display 3-25, 11-29 
displayable files 6-9 
windows 3-22, 11-39 


Index 


sizing a window 3-21 to 3-23 
function key method 2-7, 3-23, 11-54 
mouse method 2-7, 3-22 
SIZE command 2-7, 3-22 to 3-30 
size limits 3-22, 11-39 
while moving it 3-25, 11-29 
SLcommand 10-14, 11-39 
SLOAD command 6-10, 11-40 
menu selection 11-9 
—s debugger option 1-12, 1-14 
software breakpoints. See breakpoints (software) 
software checklist EMU3; EVM3 
PC systems S/M 1-3 
Sun systems S/M 3-2 
VAX systems S/M 2-2 
SOUND command 11-40, E-2 
SRcommand 10-14, 11-40 
SSAVE command 9-9, 11-41 
menu selection 11-10 
STEP command 2-17, 6-14, 11-41 
from the menu bar 4-10 
function key entry 4-10, 11-54 
stopping points 10-13 to 10-14 
adding 10-14, 11-36 
deleting 10-14, 11-37, 11-40 
listing 10-14, 11-39 
resetting 10-14, 11-40 
structures 
direct reference operator 12-2 
displaying/modifying contents 7-12 
format in DISP window 2-22, 7-13, 11-19 
indirect reference operator 12-2 
switch settings 
default settings EMU 4 to 5; EVM4,5 
I/O address space 1-12, 1-14; EMU 4 to 5, 12; 
EVM 5, 10 
your settings EMU5; EVM5 
symbol table 
definition F-6 
loading without object code 1-12, 1-15, 6-10, 
11-40 
symbolic addresses 7-7 
SYSTEM command 4-19 to 4-20, 11-42 
system commands 4-19 to 4-20, 11-2, 11-4 
ALIAS command 2-27, 4-17 to 4-18, 11-12 
CD command 2-20, 4-20, 6-11, 11-15 
CLS command 2-20, 4-5, 11-16 
DIR command 2-20, 4-20, 11-18 
DLOG command 4-6 to 4-8, 11-4, 11-20 
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system commands (continued) 
ECHO command 4-13, 11-4, 11-21 
from debugger command line 4-19 
IF/ELSE/ENDIF commands 4-14 to 4-20, 11-4, 
11-23 
conditions 4-16, 11-24 
predefined constants 4-14 
LOOP/ENDLOOP commands 4-15 to 4-20, 
11-4, 11-24 
conditions 4-16, 11-25 
QUIT command 2-27, 11-34 
RESET command 2-4, 11-34 
SOUND command 11-40, E-2 
SYSTEM command 4-19 to 4-20, 11-42 
system shell 4-20 
TAKE command 4-12, 5-12, 11-43 
UNALIAS command 4-18, 11-43 
USE command 6-11, 11-44 
system overview _ iii 
system shells 4-19 to 4-20 
definition F-6 


-t debugger option 1-12, 1-15 
during debugger invocation 5-2, D-1 
with D_OPTIONS environment 
variable EMU12; EVM9; SIM 1-7 
TAKE command 4-12, 5-12, 11-43 
executing log file 4-6 
reading new memory map 5-12 
target cable connections EMU 7 
target system EMU 2 
connection to emulator A-1 to A-8; EMU 8 
definition F-6 
memory definition for debugger 5-1 to 5-19 
resetting 2-4, 11-34 
terminating the debugger 11-34 
text files 
displaying 2-14, 6-9 
troubleshooting 
when using the emulator C-1 to C-6 
tutorial 
introductory 2-1 to 2-27 
type casting 2-23, 12-4 
type checking 2-19, 7-2 
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UNALIAS command 4-18, 11-43 


UNIX 
exiting from system shell 11-42 


unmarking areas 10-11 to 10-22 
USE command 6-11, 11-44 


-v debugger option 1-12, 1-15 
with D_OPTIONS environment variable EMU 12; 
EVM9 
VAA command 10-22, 11-44 
VAC command 10-22, 11-44 
variables 
aggregate values in DISP window 2-20, 3-16, 
7-12 to 7-14, 11-18 
determining type 7-2 
displaying in different numeric format 2-23, 12-5 
displaying/modifying 7-14 to 7-16 
scalar values in WATCH window 3-17, 7-14 to 
7-16 
verifying 
installation EMU 13; EVM 11 
PC systems SIM 1-8 
Sun systems S/M 3-3 to 3-4 
VAX systems S/M 2-4 
VGA 
definition F-6 
viewing profile data 10-17 to 10-21 
associated code 10-21 
data accuracy 10-19 
displaying areas 10-19 to 10-22 
displaying different data 10-17 to 10-22 
sorting data 10-19 
void expressions 12-4 
VRcommand 11-45 


WA command 2-16, 3-17, 4-11 to 4-13, 7-15, 11-45 
display formats 2-23, 11-45 
menu selection 11-9 


watch commands 
menu selections 11-9 
pulldown menu 7-15 
WA command 2-16, 4-11 to 4-13, 7-15, 11-45 
WD command 2-18, 7-16, 11-46 
WRcommand 2-19 to 2-28, 7-16, 11-47 
WATCH window 2-16, 3-5, 3-17, 7-2, 7-14 to 7-16, 
11-45, 11-46, 11-47 
adding items 7-15, 11-45 
closing 3-29 to 3-30, 7-16 
colors 9-6 
customizing 9-6 
definition F-6 
deleting items 7-16 
editing values 7-4 
effects of LOAD command 7-14 
effects of SLOAD command 7-14 
labeling watched data 7-15, 11-45 
opening 7-15, 11-45 
WD command 2-18, 3-17, 7-16, 11-46 
menu selection 11-9 


WHATIS command 2-19, 7-2, 11-46 
WIN command 2-5, 3-20, 11-46 


window commands 11-2, 11-3 
MOVE command 11-29 
SIZE command 3-22 to 3-30, 11-39 
WIN command 2-5, 3-20, 11-46 
ZOOM command 2-8, 3-23 to 3-30, 11-47 


windows’ 3-5 to 3-17 

active window 3-19 to 3-21 

border styles 9-8, 11-14 

CALLS window 3-5, 3-9, 6-2, 6-9 

closing 3-29 

COMMAND window _ 3-5, 3-6, 4-2 

commands 11-2, 11-3 
MOVE command 2-9, 3-24, 11-29 
SIZE command 2-7, 3-22 to 3-30, 11-39 
WIN command 2-5, 3-20, 11-46 
ZOOM command 2-8 to 2-28, 3-23 to 3-30, 

11-47 
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windows (continued) 
CPU window _ 3-5, 3-15, 7-2, 7-10 
definition F-6 
DISASSEMBLY window _ 3-5, 3-7, 6-2, 6-4 
DISP window 3-5, 3-16, 7-2, 7-12 to 7-14 
editing 3-28 
FILE window _ 3-5, 3-8, 6-2, 6-4, 6-8 
MEMORY window _ 3-5, 3-12 to 3-14, 7-2, 7-6 to 
7-9 
moving 2-9, 3-24 to 3-26, 11-29 
function keys 3-25, 11-54 
mouse method 3-24 
MOVE command 3-24 
XY positions 3-25, 11-29 
PROFILE window _ 3-5, 3-11 
resizing 2-7, 3-21 to 3-23 
function keys 3-23, 11-54 
mouse method 3-22 
SIZE command 3-22 to 3-30 
size limits 3-22 
while moving 3-25, 11-29 
scrolling 2-10, 3-26 
size limits 3-22 
WATCH window _ 3-5, 3-17, 7-2, 7-14 to 7-16 
zooming 2-8, 3-23 to 3-25 
WRcommand 2-19 to 2-28, 3-17, 7-16, 11-47 
menu selection 11-9 


—x debugger option 1-12, 1-15; EMU 12; EVM 10; 
SIM 1-7 


-z shell option 1-11 
ZOOM command 2-8, 3-23 to 3-30, 11-47 
zooming a window 

mouse method 2-8, 3-23 

ZOOM command 2-8, 3-24 
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